From 79a98cb44e7845e8747c5134aea5721b7270b756 Mon Sep 17 00:00:00 2001
From: Jake Boone <jakeboone02@gmail.com>
Date: Thu, 13 Aug 2026 15:55:45 -0700
Subject: [PATCH 1/3] Component-level cleanup

---
 AGENTS.md                                     |  11 +-
 CHANGELOG.md                                  |   3 +
 .../src/lib/components/Rule.svelte            |   5 +-
 .../src/lib/components/RuleComponents.svelte  | 108 ++++++++++--------
 .../src/lib/components/RuleGroup.svelte       |   4 +-
 .../src/lib/components/RuleSubQuery.svelte    |   5 +-
 .../src/lib/components/ValueEditor.svelte     |   4 +-
 .../src/lib/types/controls.ts                 |   2 +-
 .../src/lib/types/props.ts                    |  18 ++-
 .../src/lib/types/types.test-d.ts             |   8 ++
 10 files changed, 103 insertions(+), 65 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ebfe854..488af70 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -97,9 +97,18 @@ Runes only. No Svelte 4 idioms — no `export let`, no `$:`, no stores for compo
 - `{#snippet}` / `{@render}` for slot-like customization: each control is a top-level snippet prop, with the `controls` object as the escape hatch for passing components. Snippets and components are indistinguishable at runtime, so a snippet used as a control is wrapped as `{ snippet }` (see `internal/Control.svelte`) — never invoke a compiled component or snippet by hand
 - `setContext`/`getContext` for cross-tree config instead of prop drilling — but context is set once at init, so pass a getter or a `$state` object if the value must stay reactive
 
+#### Destructuring `$props()`
+
+Two conventions, and the choice is not stylistic:
+
+- **Leaf controls destructure**: `const { value, handleOnChange }: ValueSelectorProps = $props();`. They read their props during render, so the destructured snapshot is what the template already tracks.
+- **Forwarding components don't**: `const props: RuleProps = $props();`, then `props.schema` at the point of use. Destructuring reads every prop eagerly, at init; components that hand props onward (or build getter-backed prop bags — see `internal/lazyProps.ts`) must read them late so each downstream consumer subscribes only to what it actually touches.
+
+Don't name a local `props` in a component that also destructures `$props()` — svelte2tsx generates a conflicting binding and `svelte-check` fails with "`$props` used before its declaration." Name it for what it holds (`ruleProps`).
+
 ### TypeScript
 
-- Generics with constraints, mirroring RQB's `RG extends RuleGroupTypeAny`, `F extends FullField`, etc.
+- Generics with constraints, mirroring RQB's `RG extends RuleGroupTypeAny`, `F extends FullField`, etc. `F` is always the _field object_ type — including in `RuleProps`, where RQB parameterizes by field _name_ instead. Use `GetOptionIdentifierType<F>` for the name.
 - Always `import type` for type-only imports
 - Re-export core types from the barrel rather than redefining them
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bce837a..f7f7670 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -41,6 +41,9 @@ Control elements are now composed the Svelte way. Each of the 24 control names i
 - The `query` prop is documented as an input rather than the authority: it wins whenever it changes, and local edits stand in between. Note that a `query` prop rebuilt as a fresh object on every read is indistinguishable from a deliberate change and will revert every edit; pass a stable reference.
 - Option lists are `$derived(prepareOptionList(...))` rather than read back off a manager, and structural options (`fields`, `operators`, `combinators`, `translations`, `maxLevels`, `disabled`, `validator`, `idGenerator`, the `autoSelect*` flags) are re-derived from props instead of pushed into a mutable instance via `reconfigure`. Changing them mid-session still preserves the query and the undo/redo history.
 - Undo/redo history is two `$state.raw` stacks with coalescing delegated to core's `shouldCoalesce`, so the coalescing rule cannot drift from core's.
+- **Breaking:** `RuleProps<F>` and `RuleGroupProps<F>` are parameterized by the _field object_ type, like every other props interface in this package. `RuleProps` previously took the field _name_ (`F extends string`, RQB's convention for that one interface) and `RuleGroupProps` took `F extends FullOption`; both are now `F extends FullField`, with the field name obtained via `GetOptionIdentifierType<F>`. `CommonSubComponentProps` and `SelectorOrEditorProps` are likewise constrained to `FullField` rather than `FullOption`.
+- `Rule`, `RuleGroup`, and `ValueEditor` are generic over the same `F`/`O`. `ValueEditor` previously hardcoded `ValueEditorProps<FullField, string>`, so a replacement value editor was better typed than the built-in one.
+- `RuleComponents` takes `mode`, `rule: { props, parts }`, and (in `subQuery` mode) `subQuery: { props, parts }`, replacing four flat props. The two `(props, parts)` pairs — the rule's, and the subquery's own query-builder state — are now visibly paired, and whether a rule renders a `matchModeEditor` is decided by the explicit `mode` discriminator rather than by the presence of the subquery state.
 - `QueryBuilder` publishes context as `setQueryBuilderContext(() => state.context)` rather than an `Object.defineProperty` reflection loop, so the key set is no longer snapshotted at initialization. `getQueryBuilderContext` returns a getter.
 - Minimum `@react-querybuilder/core` is now 8.23.0, for the query-tool `freeze` opt-out (deep-freezing a Svelte `$state` proxy throws), `shouldCoalesce`, `controlKeys`/`controlKind`, and `DefaultFieldProp`/`DefaultOperatorProp`.
 
diff --git a/packages/svelte-querybuilder/src/lib/components/Rule.svelte b/packages/svelte-querybuilder/src/lib/components/Rule.svelte
index 6eba0bb..1014c93 100644
--- a/packages/svelte-querybuilder/src/lib/components/Rule.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/Rule.svelte
@@ -5,7 +5,8 @@
   Port of React Query Builder's `Rule`. A thin wrapper around `RuleComponents.svelte`, or around
   `RuleSubQuery.svelte` when the rule's field supports match modes.
 -->
-<script lang="ts" generics="F extends string = string, O extends string = string">
+<script lang="ts" generics="F extends FullField = FullField, O extends string = string">
+  import type { FullField } from '@react-querybuilder/core';
   import { TestID } from '@react-querybuilder/core';
   import { createRuleParts } from '../reactive/ruleParts.svelte.js';
   import type { RuleProps } from '../types/props.js';
@@ -26,6 +27,6 @@
   {#if parts.hasSubQuery}
     <RuleSubQuery {props} {parts} />
   {:else}
-    <RuleComponents {props} {parts} />
+    <RuleComponents mode="rule" rule={{ props, parts }} />
   {/if}
 </div>
diff --git a/packages/svelte-querybuilder/src/lib/components/RuleComponents.svelte b/packages/svelte-querybuilder/src/lib/components/RuleComponents.svelte
index 313fbc7..2569734 100644
--- a/packages/svelte-querybuilder/src/lib/components/RuleComponents.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/RuleComponents.svelte
@@ -2,9 +2,10 @@
   @component
   The controls that make up a rule, without the wrapping `<div>`.
 
-  Port of React Query Builder's `RuleComponents`. When `subQuery`/`subQueryProps` are supplied
-  (by `RuleSubQuery.svelte`), the subquery's group header and body are rendered in `<div>`s
-  around the rule's own action buttons.
+  Port of React Query Builder's `RuleComponents`. In `subQuery` mode (used by
+  `RuleSubQuery.svelte`) the subquery's group header and body are rendered in `<div>`s around
+  the rule's own action buttons, which is why one instance has to hold two `(props, parts)`
+  pairs from two separate query-builder states.
 -->
 <script lang="ts">
   import { TestID } from '@react-querybuilder/core';
@@ -16,22 +17,29 @@
   import RuleGroupBody from './RuleGroupBody.svelte';
   import RuleGroupHeader from './RuleGroupHeader.svelte';
 
-  const {
-    props,
-    parts,
-    subQueryProps,
-    subQueryParts,
-  }: {
-    props: RuleProps;
-    parts: RuleParts;
-    subQueryProps?: RuleGroupProps;
-    subQueryParts?: RuleGroupParts;
-  } = $props();
+  /**
+   * `mode` is the discriminator, not the presence of `subQuery`: in `subQuery` mode the rule
+   * renders a `matchModeEditor` instead of the operator/value controls, and that choice is a
+   * statement about the rule, not a side effect of having been handed a second state.
+   */
+  type Props =
+    | { mode: 'rule'; rule: { props: RuleProps; parts: RuleParts }; subQuery?: never }
+    | {
+        mode: 'subQuery';
+        rule: { props: RuleProps; parts: RuleParts };
+        subQuery: { props: RuleGroupProps; parts: RuleGroupParts };
+      };
 
-  const schema = $derived(props.schema);
-  const rule = $derived(props.rule);
-  const translations = $derived(props.translations);
-  const path = $derived(props.path);
+  const { mode, rule, subQuery }: Props = $props();
+
+  const ruleProps = $derived(rule.props);
+  const parts = $derived(rule.parts);
+
+  const schema = $derived(ruleProps.schema);
+  /** The `RuleType` itself, as distinct from the `rule` prop, which is its props/parts pair. */
+  const ruleObj = $derived(ruleProps.rule);
+  const translations = $derived(ruleProps.translations);
+  const path = $derived(ruleProps.path);
   const classNames = $derived(parts.classNames);
   const ctx = $derived(parts.ctx);
 
@@ -51,7 +59,7 @@
       return parts.disabled;
     },
     get context() {
-      return props.context;
+      return ruleProps.context;
     },
     get validation() {
       return ctx.validationResult;
@@ -60,7 +68,7 @@
       return schema;
     },
     get rule() {
-      return rule;
+      return ruleObj;
     },
   };
 
@@ -88,7 +96,7 @@
       return classNames.shiftActions;
     },
     get ruleOrGroup() {
-      return rule;
+      return ruleObj;
     },
     get shiftUp() {
       return parts.shiftRuleUp;
@@ -97,10 +105,10 @@
       return parts.shiftRuleDown;
     },
     get shiftUpDisabled() {
-      return props.shiftUpDisabled;
+      return ruleProps.shiftUpDisabled;
     },
     get shiftDownDisabled() {
-      return props.shiftDownDisabled;
+      return ruleProps.shiftDownDisabled;
     },
   });
 
@@ -113,10 +121,10 @@
       return translations.fields.title;
     },
     get value() {
-      return rule.field;
+      return ruleObj.field;
     },
     get operator() {
-      return rule.operator;
+      return ruleObj.operator;
     },
     get className() {
       return classNames.fields;
@@ -129,7 +137,7 @@
   const matchModeEditorProps = withCommonProps(common, {
     testID: TestID.matchModeEditor,
     get field() {
-      return rule.field;
+      return ruleObj.field;
     },
     get fieldData() {
       return parts.fieldData;
@@ -144,7 +152,7 @@
       return translations.matchThreshold.placeholderName;
     },
     get match() {
-      return rule.match ?? { mode: 'all' };
+      return ruleObj.match ?? { mode: 'all' };
     },
     get className() {
       return classNames.matchMode;
@@ -160,7 +168,7 @@
   const operatorSelectorProps = withCommonProps(common, {
     testID: TestID.operators,
     get field() {
-      return rule.field;
+      return ruleObj.field;
     },
     get fieldData() {
       return parts.fieldData;
@@ -172,7 +180,7 @@
       return ctx.operators;
     },
     get value() {
-      return rule.operator;
+      return ruleObj.operator;
     },
     get className() {
       return classNames.operators;
@@ -185,7 +193,7 @@
   const valueSourceSelectorProps = withCommonProps(common, {
     testID: TestID.valueSourceSelector,
     get field() {
-      return rule.field;
+      return ruleObj.field;
     },
     get fieldData() {
       return parts.fieldData;
@@ -197,7 +205,7 @@
       return ctx.valueSourceOptions;
     },
     get value() {
-      return rule.valueSource ?? 'value';
+      return ruleObj.valueSource ?? 'value';
     },
     get className() {
       return classNames.valueSource;
@@ -210,7 +218,7 @@
   const valueEditorProps = withCommonProps(common, {
     testID: TestID.valueEditor,
     get field() {
-      return rule.field;
+      return ruleObj.field;
     },
     get fieldData() {
       return parts.fieldData;
@@ -219,13 +227,13 @@
       return translations.value.title;
     },
     get operator() {
-      return rule.operator;
+      return ruleObj.operator;
     },
     get value() {
-      return rule.value;
+      return ruleObj.value;
     },
     get valueSource() {
-      return rule.valueSource ?? 'value';
+      return ruleObj.valueSource ?? 'value';
     },
     get type() {
       return ctx.valueEditorType;
@@ -265,7 +273,7 @@
       return classNames.cloneRule;
     },
     get ruleOrGroup() {
-      return rule;
+      return ruleObj;
     },
     get handleOnClick() {
       return parts.cloneRule;
@@ -284,29 +292,29 @@
       return classNames.lockRule;
     },
     get ruleOrGroup() {
-      return rule;
+      return ruleObj;
     },
     get handleOnClick() {
       return parts.toggleLockRule;
     },
     get disabledTranslation() {
-      return props.parentDisabled ? undefined : translations.lockRuleDisabled;
+      return ruleProps.parentDisabled ? undefined : translations.lockRuleDisabled;
     },
   });
 
   const muteRuleActionProps = withCommonProps(common, {
     testID: TestID.muteRule,
     get label() {
-      return rule.muted ? translations.unmuteRule.label : translations.muteRule.label;
+      return ruleObj.muted ? translations.unmuteRule.label : translations.muteRule.label;
     },
     get title() {
-      return rule.muted ? translations.unmuteRule.title : translations.muteRule.title;
+      return ruleObj.muted ? translations.unmuteRule.title : translations.muteRule.title;
     },
     get className() {
       return classNames.muteRule;
     },
     get ruleOrGroup() {
-      return rule;
+      return ruleObj;
     },
     get handleOnClick() {
       return parts.toggleMuteRule;
@@ -325,7 +333,7 @@
       return classNames.removeRule;
     },
     get ruleOrGroup() {
-      return rule;
+      return ruleObj;
     },
     get handleOnClick() {
       return parts.removeRule;
@@ -339,8 +347,8 @@
 {#if parts.showFieldSelector}
   <Control control={controls.fieldSelector} props={fieldSelectorProps} />
 {/if}
-{#if schema.autoSelectField || rule.field !== translations.fields.placeholderName}
-  {#if subQueryParts}
+{#if schema.autoSelectField || ruleObj.field !== translations.fields.placeholderName}
+  {#if mode === 'subQuery'}
     <Control control={controls.matchModeEditor} props={matchModeEditorProps} />
   {:else}
     <Control control={controls.operatorSelector} props={operatorSelectorProps} />
@@ -352,9 +360,9 @@
     {/if}
   {/if}
 {/if}
-{#if subQueryParts && subQueryProps}
-  <div class={subQueryParts.classNames.header}>
-    <RuleGroupHeader props={subQueryProps} parts={subQueryParts} />
+{#if subQuery}
+  <div class={subQuery.parts.classNames.header}>
+    <RuleGroupHeader props={subQuery.props} parts={subQuery.parts} />
   </div>
 {/if}
 {#if schema.showCloneButtons}
@@ -367,8 +375,8 @@
   <Control control={controls.muteRuleAction} props={muteRuleActionProps} />
 {/if}
 <Control control={controls.removeRuleAction} props={removeRuleActionProps} />
-{#if subQueryParts && subQueryProps}
-  <div class={subQueryParts.classNames.body}>
-    <RuleGroupBody props={subQueryProps} parts={subQueryParts} />
+{#if subQuery}
+  <div class={subQuery.parts.classNames.body}>
+    <RuleGroupBody props={subQuery.props} parts={subQuery.parts} />
   </div>
 {/if}
diff --git a/packages/svelte-querybuilder/src/lib/components/RuleGroup.svelte b/packages/svelte-querybuilder/src/lib/components/RuleGroup.svelte
index 0fde6aa..c0612f6 100644
--- a/packages/svelte-querybuilder/src/lib/components/RuleGroup.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/RuleGroup.svelte
@@ -9,8 +9,8 @@
   Nested groups and rules are rendered through `schema.controls`, so this component never
   imports itself and replacement components apply at every level.
 -->
-<script lang="ts" generics="F extends FullOption = FullOption, O extends string = string">
-  import type { FullOption } from '@react-querybuilder/core';
+<script lang="ts" generics="F extends FullField = FullField, O extends string = string">
+  import type { FullField } from '@react-querybuilder/core';
   import { TestID } from '@react-querybuilder/core';
   import { createRuleGroupParts } from '../reactive/ruleGroupParts.svelte.js';
   import type { RuleGroupProps } from '../types/props.js';
diff --git a/packages/svelte-querybuilder/src/lib/components/RuleSubQuery.svelte b/packages/svelte-querybuilder/src/lib/components/RuleSubQuery.svelte
index 5ad0db3..d194a77 100644
--- a/packages/svelte-querybuilder/src/lib/components/RuleSubQuery.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/RuleSubQuery.svelte
@@ -77,4 +77,7 @@
   const subGroupParts = createRuleGroupParts(() => subGroupProps);
 </script>
 
-<RuleComponents {props} {parts} subQueryProps={subGroupProps} subQueryParts={subGroupParts} />
+<RuleComponents
+  mode="subQuery"
+  rule={{ props, parts }}
+  subQuery={{ props: subGroupProps, parts: subGroupParts }} />
diff --git a/packages/svelte-querybuilder/src/lib/components/ValueEditor.svelte b/packages/svelte-querybuilder/src/lib/components/ValueEditor.svelte
index 38930c8..e900ca5 100644
--- a/packages/svelte-querybuilder/src/lib/components/ValueEditor.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/ValueEditor.svelte
@@ -5,7 +5,7 @@
   Port of React Query Builder's `ValueEditor`. The reset effect lives in
   `createValueEditorReset` (the one piece with a timing hazard); the rest is derived here.
 -->
-<script lang="ts">
+<script lang="ts" generics="F extends FullField = FullField, O extends string = string">
   import type { FullField } from '@react-querybuilder/core';
   import {
     coerceBigIntValue,
@@ -22,7 +22,7 @@
   import { createValueEditorReset } from '../reactive/valueEditorEffect.svelte.js';
   import type { ValueEditorProps, ValueSelectorProps } from '../types/props.js';
 
-  const props: ValueEditorProps<FullField, string> = $props();
+  const props: ValueEditorProps<F, O> = $props();
 
   /** Stable prefix for `radio` input ids, so each `<label for>` association is unique. */
   const uid = $props.id();
diff --git a/packages/svelte-querybuilder/src/lib/types/controls.ts b/packages/svelte-querybuilder/src/lib/types/controls.ts
index 3ff4fce..505ff13 100644
--- a/packages/svelte-querybuilder/src/lib/types/controls.ts
+++ b/packages/svelte-querybuilder/src/lib/types/controls.ts
@@ -161,7 +161,7 @@ export interface ControlPropsMap<F extends FullField, O extends string> {
    *
    * @default Rule
    */
-  rule: RuleProps;
+  rule: RuleProps<F, O>;
   /**
    * Rule group layout control.
    *
diff --git a/packages/svelte-querybuilder/src/lib/types/props.ts b/packages/svelte-querybuilder/src/lib/types/props.ts
index 6ebd793..dca6b63 100644
--- a/packages/svelte-querybuilder/src/lib/types/props.ts
+++ b/packages/svelte-querybuilder/src/lib/types/props.ts
@@ -46,7 +46,7 @@ import type { LabelNode, Translations, TranslationWithLabel } from './translatio
  * @group Props
  */
 export interface CommonSubComponentProps<
-  F extends FullOption = FullField,
+  F extends FullField = FullField,
   O extends string = string,
 > {
   /**
@@ -97,7 +97,7 @@ export interface CommonSubComponentProps<
  * @group Props
  */
 export interface SelectorOrEditorProps<
-  F extends FullOption = FullField,
+  F extends FullField = FullField,
   O extends string = string,
 > extends CommonSubComponentProps<F, O> {
   value?: string;
@@ -369,10 +369,13 @@ interface CommonRuleAndGroupProps<F extends FullField = FullField, O extends str
 /**
  * `RuleGroup` props.
  *
+ * `F` is the *field object* type, not the field name — the same convention as every other props
+ * interface in this package. Use `GetOptionIdentifierType<F>` to get at the name.
+ *
  * @group Props
  */
 export interface RuleGroupProps<
-  F extends FullOption = FullOption,
+  F extends FullField = FullField,
   O extends string = string,
 > extends CommonRuleAndGroupProps<F, O> {
   ruleGroup: RuleGroupTypeAny<RuleType<GetOptionIdentifierType<F>, O>>;
@@ -381,13 +384,16 @@ export interface RuleGroupProps<
 /**
  * `Rule` props.
  *
+ * `F` is the *field object* type, not the field name (which is RQB's convention for this one
+ * interface). See {@link RuleGroupProps}.
+ *
  * @group Props
  */
 export interface RuleProps<
-  F extends string = string,
+  F extends FullField = FullField,
   O extends string = string,
-> extends CommonRuleAndGroupProps<FullOption<F>, O> {
-  rule: RuleType<F, O>;
+> extends CommonRuleAndGroupProps<F, O> {
+  rule: RuleType<GetOptionIdentifierType<F>, O>;
 }
 
 /**
diff --git a/packages/svelte-querybuilder/src/lib/types/types.test-d.ts b/packages/svelte-querybuilder/src/lib/types/types.test-d.ts
index 486b832..1b3b19f 100644
--- a/packages/svelte-querybuilder/src/lib/types/types.test-d.ts
+++ b/packages/svelte-querybuilder/src/lib/types/types.test-d.ts
@@ -95,6 +95,14 @@ assertType<Translations>(ruleProps.translations);
 declare const ruleGroupProps: RuleGroupProps;
 // @ts-expect-error use `ruleGroup.combinator`
 assertType<unknown>(ruleGroupProps.combinator);
+
+// `F` is the field *object* type in both, not the field name (which is RQB's convention for
+// `RuleProps`). The name comes from `GetOptionIdentifierType<F>`.
+declare const narrowRuleProps: RuleProps<FullField<'f1' | 'f2'>, 'op'>;
+assertType<'f1' | 'f2'>(narrowRuleProps.rule.field);
+assertType<'op'>(narrowRuleProps.rule.operator);
+declare const narrowRuleGroupProps: RuleGroupProps<FullField<'f1' | 'f2'>, 'op'>;
+assertType<Schema<FullField<'f1' | 'f2'>, 'op'>>(narrowRuleGroupProps.schema);
 // #endregion
 
 // #region Schema

From fcb636c52d8932ec5c9cf30014d8f6241756a0a1 Mon Sep 17 00:00:00 2001
From: Jake Boone <jakeboone02@gmail.com>
Date: Thu, 13 Aug 2026 17:04:00 -0700
Subject: [PATCH 2/3] New component/repo model

---
 AGENTS.md                                     | 51 +++++++++-----
 CHANGELOG.md                                  |  5 ++
 README.md                                     | 11 +--
 bun.lock                                      | 16 +----
 docs/differences-from-react-querybuilder.md   | 30 +++++++--
 examples/demo/package.json                    | 19 ------
 examples/demo/src/main.ts                     |  6 --
 examples/demo/svelte.config.js                |  9 ---
 examples/demo/tsconfig.json                   | 11 ---
 examples/demo/vite.config.ts                  | 28 --------
 package.json                                  |  1 +
 packages/svelte-querybuilder/package.json     |  8 ++-
 .../scripts/fetch-fixtures.ts                 | 20 ++++--
 packages/svelte-querybuilder/src/app.d.ts     | 11 +++
 .../svelte-querybuilder/src/app.html          |  8 +--
 .../src/lib/components/MatchModeEditor.svelte |  4 +-
 .../src/lib/components/RuleComponents.svelte  | 67 +++++++++++--------
 .../src/lib/components/RuleGroup.svelte       |  2 +
 .../src/lib/components/RuleGroupBody.svelte   |  4 +-
 .../src/lib/components/RuleGroupHeader.svelte | 54 ++++++++-------
 .../src/lib/components/ShiftActions.svelte    |  5 +-
 .../src/lib/components/ValueEditor.svelte     |  8 +--
 .../src/routes/+layout.svelte                 | 19 ++++++
 .../src/routes/+page.svelte                   | 22 ++++--
 .../src/routes/playground.css                 |  0
 packages/svelte-querybuilder/svelte.config.js | 14 +++-
 .../test/conformance/cases.ts                 | 25 ++++++-
 .../conformance/classnames-post-flush.test.ts | 14 ++--
 .../test/conformance/classnames.test.ts       |  4 +-
 .../test/conformance/extract.ts               | 19 ++++++
 packages/svelte-querybuilder/tsconfig.json    | 19 +++++-
 packages/svelte-querybuilder/vite.config.ts   | 33 +++------
 packages/svelte-querybuilder/vitest.config.ts | 31 +++++++++
 vitest.config.ts                              |  2 +-
 34 files changed, 356 insertions(+), 224 deletions(-)
 delete mode 100644 examples/demo/package.json
 delete mode 100644 examples/demo/src/main.ts
 delete mode 100644 examples/demo/svelte.config.js
 delete mode 100644 examples/demo/tsconfig.json
 delete mode 100644 examples/demo/vite.config.ts
 create mode 100644 packages/svelte-querybuilder/src/app.d.ts
 rename examples/demo/index.html => packages/svelte-querybuilder/src/app.html (50%)
 create mode 100644 packages/svelte-querybuilder/src/routes/+layout.svelte
 rename examples/demo/src/App.svelte => packages/svelte-querybuilder/src/routes/+page.svelte (89%)
 rename examples/demo/src/app.css => packages/svelte-querybuilder/src/routes/playground.css (100%)
 create mode 100644 packages/svelte-querybuilder/vitest.config.ts

diff --git a/AGENTS.md b/AGENTS.md
index 488af70..5e8ed50 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,11 +10,11 @@ This guide covers `svelte-querybuilder` development: code style, workflow, and o
 
 ## Project Overview
 
-Svelte 5 port of [React Query Builder](https://react-querybuilder.js.org). Bun workspace monorepo:
+A Svelte 5 library that shares its logic layer with [React Query Builder](https://react-querybuilder.js.org) — not a transliteration of it. Behavior and rendered DOM are held to RQB; the component API is designed for Svelte. Bun workspace monorepo:
 
-- **Main package**: `packages/svelte-querybuilder` - Svelte 5 components + types
+- **Main package**: `packages/svelte-querybuilder` - Svelte 5 components + types, plus the development playground under `src/routes`
 - **Logic layer**: `@react-querybuilder/core` (npm dependency) - query manipulation, parsers, formatters, defaults, i18n strings. **Not vendored.** Re-exported from the barrel so consumers never need a direct core dependency.
-- **Examples**: `examples/*` (workspace glob; may be empty)
+- **Examples**: `examples/*` (workspace glob) - currently just `sveltekit`, which doubles as the SSR gate
 
 See `CHANGELOG.md` for release history.
 
@@ -49,10 +49,12 @@ Run from repo root unless noted.
 - `bun run check:exports` - `attw` on a packed tarball + `dist` specifier lint (needs a build first)
 - `bun lint` - oxlint
 - `bun fmt` / `bun fmt:check` - oxfmt (run `bun fmt` after changes)
+- `bun run conformance` - Fetches the RQB fixture set and runs the conformance suites
 
-**Build:**
+**Build and run:**
 
 - `bun run build` - `svelte-package` into `dist`, then compile SCSS
+- `bun run dev` - Serves the playground at `packages/svelte-querybuilder/src/routes` against library source
 
 Before submitting a PR, run the CI sequence: `bun run check:all`.
 
@@ -61,14 +63,23 @@ Before submitting a PR, run the CI sequence: `bun run check:all`.
 ### Structure
 
 ```
-packages/svelte-querybuilder/src/lib/
-├── *.svelte           # Components (PascalCase.svelte)
-├── types/             # TypeScript defs
-├── utils/             # Svelte-specific utilities (camelCase.ts)
-├── styles/            # SCSS (_svelte.scss layered over core's partials)
-└── index.ts           # Barrel: components, types, and `export * from '@react-querybuilder/core'`
+packages/svelte-querybuilder/
+├── src/lib/           # The only published code
+│   ├── *.svelte       # Components (PascalCase.svelte)
+│   ├── types/         # TypeScript defs
+│   ├── utils/         # Svelte-specific utilities (camelCase.ts)
+│   ├── styles/        # SCSS (_svelte.scss layered over core's partials)
+│   └── index.ts       # Barrel: components, types, `export * from '@react-querybuilder/core'`
+├── src/routes/        # SvelteKit dev playground; never packaged
+└── test/conformance/  # Fixture-driven parity suites (fixtures are downloaded, not generated)
 ```
 
+The package is a SvelteKit project so that `src/routes` can exist, but Kit is a development
+convenience only: `svelte-package` reads `src/lib` and nothing else. `vite.config.ts` serves the
+playground; the unit suite has its own `vitest.config.ts` on the bare `svelte()` plugin, because
+`sveltekit()` resolves its project from the working directory and Vitest runs the package from
+the monorepo root.
+
 ### Naming
 
 - **Components**: PascalCase (`QueryBuilder.svelte`, `RuleGroup.svelte`)
@@ -146,16 +157,23 @@ Only fall back to `node:*` APIs when no Bun equivalent exists. Library code unde
 - Keep `data-testid` attributes matching RQB's so ported tests stay recognizable
 - Coverage threshold is 80% lines and should trend up, not down
 - SSR must not break: components have to render without `window` (`bun run test:ssr`)
+- Conformance (`bun run conformance`) compares the rendered DOM to fixtures recorded from the React package: every element's `class`, each rule group's accessible description, each element's _own_ text verbatim, and the result of curated mutation sequences. Fixtures are downloaded from a pinned upstream tag and are gitignored — never regenerate them locally, which would make the suite tautological.
 
 ## Porting from React Query Builder
 
-The React source is the spec. When porting a component:
+RQB is the spec for **behavior and rendered output**, not for the API. Two contracts, held to different standards:
+
+**Kept, deliberately.** Class names, `data-testid`s, `data-path`, element structure and document order, and each element's own text. RQB stylesheets and themes have to port over unchanged, and the conformance fixtures are only meaningful because the DOM matches. Diverging here needs a reason and a changelog note.
+
+**Ours to design.** Prop names, control maps, lifecycle flags, generic parameters, and the shape of anything a consumer configures. API parity is _not_ a goal: where RQB's surface exists to work around React — `controlElements` nesting, `enableMountQueryChange`, `useRule`-style hook returns, a `qbId` registry — build the Svelte-shaped equivalent instead of transliterating. Prefer the form a Svelte consumer would expect (top-level snippet props, `bind:`, callback props, runes) over the form that would make a diff against RQB smaller.
+
+When porting a component:
 
 1. Read the RQB source and its tests
-2. Keep prop names, class names, `data-testid`s, and DOM structure identical unless there's a reason not to
+2. Reproduce the DOM exactly; design the props for Svelte
 3. Translate hooks to runes; drop memoization
 4. Port the tests, then the component
-5. Note intentional divergences in a comment and in the changelog
+5. Note intentional divergences in a comment, in the changelog, and in `docs/differences-from-react-querybuilder.md`
 
 Document user-visible changes in `CHANGELOG.md` under `## [Unreleased]` (Keep a Changelog format, SemVer).
 
@@ -184,7 +202,8 @@ Use core's `Translations` type and default strings. Svelte-side: allow snippets
 10. Diverging from RQB class names / `data-testid`s without a reason
 11. Missing tests or accessibility coverage
 12. Editing `packages/svelte-querybuilder/dist` (generated by `svelte-package`)
-13. Extensionless or directory-style relative imports. `svelte-package` does not rewrite specifiers, so `./foo` and `./types` break Node ESM consumers. Write `./foo.js` and `./types/index.js`; a `*.svelte.ts` rune module is `*.svelte.js`, a component is `*.svelte`. `bun run check:exports` enforces this.
+13. Removing the `<!-- -->` joiners between sibling elements in `RuleComponents`, `RuleGroupHeader`, `RuleGroupBody`, `RuleGroup`, `MatchModeEditor`, `ShiftActions`, or `ValueEditor`. JSX drops whitespace-only lines between elements; Svelte collapses each gap to a single space and _keeps_ it, which would add text nodes RQB never emits. Conformance compares element text verbatim.
+14. Extensionless or directory-style relative imports. `svelte-package` does not rewrite specifiers, so `./foo` and `./types` break Node ESM consumers. Write `./foo.js` and `./types/index.js`; a `*.svelte.ts` rune module is `*.svelte.js`, a component is `*.svelte`. `bun run check:exports` enforces this.
 
 ## Quick Reference
 
@@ -196,9 +215,11 @@ Use core's `Translations` type and default strings. Svelte-side: allow snippets
 - `bun run test` - Tests
 - `bun fmt` - Format
 - `bun run test:coverage` - Coverage
+- `bun run dev` - Playground
 
 **Directories:**
 
 - `packages/svelte-querybuilder/src/lib/` - Library source (the only published code)
+- `packages/svelte-querybuilder/src/routes/` - Dev playground; never published
 - `packages/svelte-querybuilder/dist/` - Generated; never edit
-- `examples/` - Demos and starter templates
+- `examples/sveltekit/` - Starter template and the SSR gate
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f7f7670..6196c31 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,11 +21,13 @@ Control elements are now composed the Svelte way. Each of the 24 control names i
 - **Breaking:** `enableMountQueryChange`. Its behavior is now derived from first principles — see below.
 - `createRuleContext` and `createRuleGroupContext`, along with the `Derived<T>` (`{ readonly current: T }`) wrapper type. `createRuleParts`/`createRuleGroupParts` are the supported path and return getters directly.
 - `createActions`, superseded by core's `createQueryActions`.
+- The `examples/demo` package. Its content became the development playground inside the library package (see below); `examples/sveltekit` remains as the starter template and SSR gate.
 
 ### Added
 
 - Top-level snippet props for every control: `valueEditor`, `removeRuleAction`, `ruleGroup`, `actionElement`, `valueSelector`, and so on. A snippet declared inside a component's tags only becomes a prop when the name is top-level, which is what makes the idiomatic form reachable.
 - `controls`, the bulk object form, for configuration assembled programmatically. It accepts components, `null`, and snippets wrapped as `{ snippet }`.
+- A SvelteKit development playground at `packages/svelte-querybuilder/src/routes`, run with `bun run dev`. It imports library source (`$lib`) and core's SCSS rather than anything in `dist`, so component _and_ stylesheet edits hot-reload without a build. The package is now a SvelteKit project for this reason alone — `svelte-package` still reads `src/lib` and nothing else, and nothing under `src/routes` is published.
 
 ### Changed
 
@@ -40,6 +42,8 @@ Control elements are now composed the Svelte way. Each of the 24 control names i
 - `onQueryChange` fires once during initialization if and only if the initial query was seeded or normalized by the component — no query supplied, or one supplied without `id`s. A query handed over ready to use never triggers it. This is what `enableMountQueryChange` used to control, minus the flag.
 - The `query` prop is documented as an input rather than the authority: it wins whenever it changes, and local edits stand in between. Note that a `query` prop rebuilt as a fresh object on every read is indistinguishable from a deliberate change and will revert every edit; pass a stable reference.
 - Option lists are `$derived(prepareOptionList(...))` rather than read back off a manager, and structural options (`fields`, `operators`, `combinators`, `translations`, `maxLevels`, `disabled`, `validator`, `idGenerator`, the `autoSelect*` flags) are re-derived from props instead of pushed into a mutable instance via `reconfigure`. Changing them mid-session still preserves the query and the undo/redo history.
+- The conformance extractor records each element's _own_ direct text-node children verbatim, matching the `text` channel added by upstream fixture `schemaVersion` 3. Fixtures older than that do not record it, so the channel is dropped before comparison until `CONFORMANCE_TAG` is bumped to a release that publishes schema 3; both versions are accepted by the fetch script in the meantime.
+- The unit suite has its own `vitest.config.ts`. `vite.config.ts` now carries the SvelteKit plugin for the playground, and Kit resolves its project from the working directory — which is the monorepo root when Vitest runs the package as a `projects` entry.
 - Undo/redo history is two `$state.raw` stacks with coalescing delegated to core's `shouldCoalesce`, so the coalescing rule cannot drift from core's.
 - **Breaking:** `RuleProps<F>` and `RuleGroupProps<F>` are parameterized by the _field object_ type, like every other props interface in this package. `RuleProps` previously took the field _name_ (`F extends string`, RQB's convention for that one interface) and `RuleGroupProps` took `F extends FullOption`; both are now `F extends FullField`, with the field name obtained via `GetOptionIdentifierType<F>`. `CommonSubComponentProps` and `SelectorOrEditorProps` are likewise constrained to `FullField` rather than `FullOption`.
 - `Rule`, `RuleGroup`, and `ValueEditor` are generic over the same `F`/`O`. `ValueEditor` previously hardcoded `ValueEditorProps<FullField, string>`, so a replacement value editor was better typed than the built-in one.
@@ -49,6 +53,7 @@ Control elements are now composed the Svelte way. Each of the 24 control names i
 
 ### Fixed
 
+- No element renders a whitespace text node React Query Builder does not. Svelte collapses the gap between two sibling elements to a single space and keeps it, where JSX drops whitespace-only lines entirely, so a rule `<div>` was carrying ten stray text nodes and a group body up to eight. Every affected sibling pair is now joined with an `<!-- -->` comment. Invisible in any normalizing assertion, but it is real DOM: text nodes affect `childNodes`, `::first-child`-adjacent CSS, and anything walking the tree.
 - Mounting a query with rules whose `value` no longer matches their `operator` — the ones for which core's `getValueEditorReset` returns `reset: true` — is roughly 40x faster. Each such rule commits a query change during mount, and every commit was re-dirtying every prop of every control in the tree, so the cost grew quadratically in the number of reset-eligible rules (~1s for a two-rule case in an eight-rule tree). Control prop bags are now getter-backed objects built once, rather than `$derived` object literals rebuilt per commit: `Control` forwards them through `{...props}`, and Svelte's `spread_props` resolves one key at a time, so each of a control's props subscribes to only its own sources instead of to the union of all of them. Interactive editing was never affected.
 
 ## [0.1.1] - 2026-08-05
diff --git a/README.md b/README.md
index 9161b08..915d340 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # svelte-querybuilder
 
-A Svelte 5 port of [React Query Builder](https://react-querybuilder.js.org). Builds a nested query structure from a field/operator/value UI, backed by [`@react-querybuilder/core`](https://www.npmjs.com/package/@react-querybuilder/core).
+A Svelte 5 query builder: a nested query structure built from a field/operator/value UI, backed by [`@react-querybuilder/core`](https://www.npmjs.com/package/@react-querybuilder/core) — the same logic layer [React Query Builder](https://react-querybuilder.js.org) runs on, so query shapes, formatters, and parsers behave identically and the rendered DOM is class-compatible. The component API is Svelte's own.
 
 ## Install
 
@@ -61,16 +61,19 @@ The DOM is class-compatible with React Query Builder, so existing RQB stylesheet
 
 ## Docs
 
-- [Differences from React Query Builder](./docs/differences-from-react-querybuilder.md)
-- [Customization](./docs/customization.md)
+**Coming from React Query Builder?** Read [Differences from React Query Builder](./docs/differences-from-react-querybuilder.md) first. Your queries, field configuration, and CSS carry over unchanged; the component API is Svelte's, not React's.
+
+- [Differences from React Query Builder](./docs/differences-from-react-querybuilder.md) — start here if you know RQB
+- [Customization](./docs/customization.md) — snippets, `controls`, translations, context
 - [Styling](./docs/styling.md)
 - Concepts, field/operator configuration, query formats, and parsers: the [React Query Builder documentation](https://react-querybuilder.js.org/docs/intro) applies directly, since the logic layer is shared.
 
 ## Examples
 
-- [`examples/demo`](./examples/demo) — Vite + Svelte, running against library source. `bun run --filter @svelte-querybuilder/example-demo dev`
 - [`examples/sveltekit`](./examples/sveltekit) — SvelteKit, server-side rendering. Doubles as the repo's SSR gate (`bun run test:ssr`).
 
+The development playground lives in the library package itself (`packages/svelte-querybuilder/src/routes`) and runs against library source: `bun run dev`.
+
 ## Non-goals
 
 Not in v1, and not planned for the near term:
diff --git a/bun.lock b/bun.lock
index 2ed3f39..2d0eefb 100644
--- a/bun.lock
+++ b/bun.lock
@@ -27,17 +27,6 @@
         "vitest-axe": "^0.1.0",
       },
     },
-    "examples/demo": {
-      "name": "@svelte-querybuilder/example-demo",
-      "version": "0.0.0",
-      "devDependencies": {
-        "@sveltejs/vite-plugin-svelte": "^7.3.0",
-        "@types/node": "^26.2.0",
-        "svelte": "^5.56.9",
-        "svelte-check": "^4.7.6",
-        "vite": "^8.2.1",
-      },
-    },
     "examples/sveltekit": {
       "name": "@svelte-querybuilder/example-sveltekit",
       "version": "0.0.0",
@@ -61,7 +50,10 @@
       },
       "devDependencies": {
         "@arethetypeswrong/cli": "^0.18.2",
+        "@sveltejs/adapter-node": "^5.5.7",
+        "@sveltejs/kit": "^2.70.2",
         "@sveltejs/package": "^2.5.8",
+        "@sveltejs/vite-plugin-svelte": "^7.3.0",
         "svelte": "^5.56.9",
         "svelte-check": "^4.7.6",
         "typescript": "^5.9.3",
@@ -334,8 +326,6 @@
 
     "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
 
-    "@svelte-querybuilder/example-demo": ["@svelte-querybuilder/example-demo@workspace:examples/demo"],
-
     "@svelte-querybuilder/example-sveltekit": ["@svelte-querybuilder/example-sveltekit@workspace:examples/sveltekit"],
 
     "@sveltejs/acorn-typescript": ["@sveltejs/acorn-typescript@1.0.11", "", { "peerDependencies": { "acorn": "^8.9.0" } }, "sha512-LFuZUkjJ9iF7JZye/aG5XM0SFcQ5VyL0oVX4WJ9dc0Va3R3s0OauX1BESVCb+YN/ol8TAfqGDDAQsTG627Y5kw=="],
diff --git a/docs/differences-from-react-querybuilder.md b/docs/differences-from-react-querybuilder.md
index 2f3f6a8..562f46f 100644
--- a/docs/differences-from-react-querybuilder.md
+++ b/docs/differences-from-react-querybuilder.md
@@ -1,12 +1,34 @@
 # Differences from React Query Builder
 
-`svelte-querybuilder` is a port of [React Query Builder](https://react-querybuilder.js.org)'s UI layer. Both packages sit on top of the same logic layer, [`@react-querybuilder/core`](https://www.npmjs.com/package/@react-querybuilder/core), so query shapes, field/operator configuration, validation, `formatQuery`, and the parsers all behave identically. What differs is the component layer and everything React-specific about it.
+If you know [React Query Builder](https://react-querybuilder.js.org), start here. This is the orientation page for everything you already know that still applies, and everything that doesn't.
 
-This page is the complete list of intentional divergences.
+## The mental model
 
-## Rendered output is identical
+`svelte-querybuilder` is a Svelte library that **shares a logic layer** with React Query Builder — not a transliteration of it. The two packages sit on the same [`@react-querybuilder/core`](https://www.npmjs.com/package/@react-querybuilder/core), and they are held to two different standards:
 
-Element structure, document order, class names, `data-testid`s, and `data-path` attributes are intended to match React Query Builder exactly, and are verified against fixtures generated from the React package. If you find a DOM difference that is not listed here, it is a bug.
+|                                                                                                   | Contract                                                                                                                                                                                                           |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Query shapes, field/operator config, validation, `formatQuery`, the parsers, i18n string keys** | **Identical.** Same package doing the work. RQB's documentation on any of these applies verbatim.                                                                                                                  |
+| **Rendered DOM** — element structure, document order, class names, `data-testid`s, `data-path`    | **Identical, and tested.** Verified against fixtures recorded from the React package, down to each element's own text. Your RQB stylesheet, theme, and DOM-level tests port over unchanged. A difference is a bug. |
+| **Component API** — prop names, control maps, lifecycle flags, generics                           | **Designed for Svelte.** Parity is explicitly not a goal. Where RQB's surface exists to work around React, this package does the Svelte-shaped thing instead.                                                      |
+
+So: keep your queries, your field configuration, and your CSS. Expect to rewrite your markup.
+
+The rest of this page is the complete list of intentional divergences.
+
+## Quick mapping
+
+| React Query Builder                               | Here                                                                                   |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `controlElements={{ valueEditor: MyEditor }}`     | `controls={{ valueEditor: MyEditor }}`, or a top-level `{#snippet valueEditor(props)}` |
+| `<QueryBuilder query onQueryChange />`            | Same, or `bind:query`                                                                  |
+| `defaultQuery`                                    | Same                                                                                   |
+| `enableMountQueryChange`                          | Gone; derived from first principles ([below](#known-behavioral-note))                  |
+| `useRule` / `useRuleGroup`                        | `createRuleParts` / `createRuleGroupParts` (take a props _getter_)                     |
+| `dispatchQuery` / `useQueryBuilderQuery` / `qbId` | Gone; there is no store ([below](#state-management))                                   |
+| `react-querybuilder/history`                      | Built in; `showUndoRedo` + `schema.history`                                            |
+| `ReactNode` labels                                | `LabelNode = Snippet \| string`                                                        |
+| `enableDragAndDrop`                               | Not accepted ([below](#not-implemented))                                               |
 
 ## Not implemented
 
diff --git a/examples/demo/package.json b/examples/demo/package.json
deleted file mode 100644
index 0b38141..0000000
--- a/examples/demo/package.json
+++ /dev/null
@@ -1,19 +0,0 @@
-{
-  "name": "@svelte-querybuilder/example-demo",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build",
-    "preview": "vite preview",
-    "check": "svelte-check --tsconfig ./tsconfig.json"
-  },
-  "devDependencies": {
-    "@sveltejs/vite-plugin-svelte": "^7.3.0",
-    "@types/node": "^26.2.0",
-    "svelte": "^5.56.9",
-    "svelte-check": "^4.7.6",
-    "vite": "^8.2.1"
-  }
-}
diff --git a/examples/demo/src/main.ts b/examples/demo/src/main.ts
deleted file mode 100644
index eaf2c91..0000000
--- a/examples/demo/src/main.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-import 'svelte-querybuilder/dist/query-builder.css';
-import { mount } from 'svelte';
-import App from './App.svelte';
-import './app.css';
-
-export default mount(App, { target: document.querySelector('#app')! });
diff --git a/examples/demo/svelte.config.js b/examples/demo/svelte.config.js
deleted file mode 100644
index 458b64e..0000000
--- a/examples/demo/svelte.config.js
+++ /dev/null
@@ -1,9 +0,0 @@
-import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
-
-/** @type {import('@sveltejs/vite-plugin-svelte').SvelteConfig} */
-export default {
-  preprocess: vitePreprocess(),
-  compilerOptions: {
-    runes: true,
-  },
-};
diff --git a/examples/demo/tsconfig.json b/examples/demo/tsconfig.json
deleted file mode 100644
index ad5ca15..0000000
--- a/examples/demo/tsconfig.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "lib": ["esnext", "dom", "dom.iterable"],
-    "paths": {
-      "svelte-querybuilder": ["../../packages/svelte-querybuilder/src/lib/index.ts"]
-    }
-  },
-  "include": ["src/**/*.ts", "src/**/*.svelte", "*.ts"],
-  "exclude": ["node_modules", "dist"]
-}
diff --git a/examples/demo/vite.config.ts b/examples/demo/vite.config.ts
deleted file mode 100644
index 42bac28..0000000
--- a/examples/demo/vite.config.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import { svelte } from '@sveltejs/vite-plugin-svelte';
-import { fileURLToPath } from 'node:url';
-import { defineConfig } from 'vite';
-
-const resolve = (path: string) => fileURLToPath(new URL(path, import.meta.url));
-
-export default defineConfig({
-  plugins: [svelte()],
-  resolve: {
-    alias: [
-      // The demo runs against library *source*, not `dist`, so edits under
-      // `packages/svelte-querybuilder/src/lib` hot-reload here without a rebuild.
-      //
-      // The CSS alias is what keeps the demo's own import lines identical to a real consumer's:
-      // it lets `src/main.ts` write `svelte-querybuilder/dist/query-builder.css` without
-      // requiring `bun run build` to have run first. The package's compiled stylesheet is
-      // byte-identical to core's, so pointing at core's is equivalent.
-      {
-        find: /^svelte-querybuilder\/dist\/(.*)\.css$/,
-        replacement: resolve('../../node_modules/@react-querybuilder/core/dist/$1.css'),
-      },
-      {
-        find: /^svelte-querybuilder$/,
-        replacement: resolve('../../packages/svelte-querybuilder/src/lib/index.ts'),
-      },
-    ],
-  },
-});
diff --git a/package.json b/package.json
index cb3e9f9..3e55cf0 100644
--- a/package.json
+++ b/package.json
@@ -9,6 +9,7 @@
   ],
   "scripts": {
     "build": "bun run --filter svelte-querybuilder build",
+    "dev": "bun run --filter svelte-querybuilder dev",
     "check": "bun run --filter svelte-querybuilder check && bun run --filter '@svelte-querybuilder/example-*' check",
     "check:exports": "bun run --filter svelte-querybuilder check:exports",
     "check:all": "bun fmt:check && bun run build && bun run check && bun run check:exports && bun lint && bun run test:coverage && bun run conformance && bun run test:ssr",
diff --git a/packages/svelte-querybuilder/package.json b/packages/svelte-querybuilder/package.json
index 0606aee..48d6cee 100644
--- a/packages/svelte-querybuilder/package.json
+++ b/packages/svelte-querybuilder/package.json
@@ -51,12 +51,13 @@
     "build": "bun run build:main && bun run build:css",
     "build:main": "svelte-package -i src/lib -o dist && find dist \\( -name '*.test.*' -o -name '*.test-d.*' -o -name '*.spec.*' \\) -delete",
     "build:css": "mkdir -p dist/styles && cp ../../node_modules/@react-querybuilder/core/dist/*.scss dist && cp ../../node_modules/@react-querybuilder/core/dist/styles/*.scss dist/styles && cp -f src/lib/styles/*.scss dist/styles 2>/dev/null || true; bun sass --style=compressed dist",
-    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "dev": "vite dev",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
     "check:exports": "bun run ./scripts/check-dist-specifiers.ts && attw --pack . --profile esm-only --ignore-rules internal-resolution-error",
     "conformance": "bun run conformance:fetch && bun run conformance:test",
     "conformance:fetch": "bun ./scripts/fetch-fixtures.ts",
     "conformance:test": "vitest run --config vitest.conformance.config.ts",
-    "check:watch": "svelte-check --tsconfig ./tsconfig.json --watch"
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
   },
   "peerDependencies": {
     "svelte": "^5.25"
@@ -66,7 +67,10 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
+    "@sveltejs/adapter-node": "^5.5.7",
+    "@sveltejs/kit": "^2.70.2",
     "@sveltejs/package": "^2.5.8",
+    "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "svelte": "^5.56.9",
     "svelte-check": "^4.7.6",
     "typescript": "^5.9.3"
diff --git a/packages/svelte-querybuilder/scripts/fetch-fixtures.ts b/packages/svelte-querybuilder/scripts/fetch-fixtures.ts
index 7007910..060fac6 100644
--- a/packages/svelte-querybuilder/scripts/fetch-fixtures.ts
+++ b/packages/svelte-querybuilder/scripts/fetch-fixtures.ts
@@ -22,10 +22,17 @@ import * as path from 'node:path';
 export const CONFORMANCE_TAG = 'v8.22.4';
 
 /**
- * The fixture *shape* version. Not the tag: upstream may cut a dozen releases without changing
- * the schema, and a schema change must fail loudly rather than be mis-read.
+ * The fixture *shape* versions this harness understands. Not the tag: upstream may cut a dozen
+ * releases without changing the schema, and a schema change must fail loudly rather than be
+ * mis-read.
+ *
+ * Two are accepted because the schemas are nested, not alternative: 3 adds a per-element `text`
+ * channel and changes nothing else. The extractor always produces it; `stripUnrecordedChannels`
+ * in `test/conformance/cases.ts` drops it when the fixtures on disk are schema 2. So the tag can
+ * be bumped to a schema-3 release in one line, with the new channel asserted immediately and no
+ * other edit.
  */
-export const EXPECTED_SCHEMA_VERSION = 2;
+export const SUPPORTED_SCHEMA_VERSIONS: readonly number[] = [2, 3];
 
 const ASSET = 'rqb-conformance-fixtures.tar.gz';
 const RELEASE_URL = `https://github.com/react-querybuilder/react-querybuilder/releases/download/${CONFORMANCE_TAG}`;
@@ -76,10 +83,11 @@ export const fetchFixtures = async (): Promise<void> => {
   await rm(archivePath);
 
   const index = await Bun.file(path.join(fixturesDir, 'index.json')).json();
-  if (index.schemaVersion !== EXPECTED_SCHEMA_VERSION) {
+  if (!SUPPORTED_SCHEMA_VERSIONS.includes(index.schemaVersion)) {
     throw new Error(
-      `Fixture schemaVersion is ${index.schemaVersion}, expected ${EXPECTED_SCHEMA_VERSION}. ` +
-        `The fixture format changed upstream; update test/conformance before bumping the tag.`
+      `Fixture schemaVersion is ${index.schemaVersion}, expected one of ` +
+        `${SUPPORTED_SCHEMA_VERSIONS.join(', ')}. The fixture format changed upstream; update ` +
+        `test/conformance before bumping the tag.`
     );
   }
 
diff --git a/packages/svelte-querybuilder/src/app.d.ts b/packages/svelte-querybuilder/src/app.d.ts
new file mode 100644
index 0000000..a873fcf
--- /dev/null
+++ b/packages/svelte-querybuilder/src/app.d.ts
@@ -0,0 +1,11 @@
+// See https://svelte.dev/docs/kit/types#app
+//
+// No top-level `import`/`export` here, so this file is an ambient declaration and does not need
+// the `declare global` + `export {}` wrapper that the `create-svelte` template uses.
+declare namespace App {
+  // interface Error {}
+  // interface Locals {}
+  // interface PageData {}
+  // interface PageState {}
+  // interface Platform {}
+}
diff --git a/examples/demo/index.html b/packages/svelte-querybuilder/src/app.html
similarity index 50%
rename from examples/demo/index.html
rename to packages/svelte-querybuilder/src/app.html
index f34a48f..f16bf0a 100644
--- a/examples/demo/index.html
+++ b/packages/svelte-querybuilder/src/app.html
@@ -3,10 +3,10 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>svelte-querybuilder demo</title>
+    <title>svelte-querybuilder playground</title>
+    %sveltekit.head%
   </head>
-  <body>
-    <div id="app"></div>
-    <script type="module" src="/src/main.ts"></script>
+  <body data-sveltekit-preload-data="hover">
+    <div style="display: contents">%sveltekit.body%</div>
   </body>
 </html>
diff --git a/packages/svelte-querybuilder/src/lib/components/MatchModeEditor.svelte b/packages/svelte-querybuilder/src/lib/components/MatchModeEditor.svelte
index 0ce362e..31c6449 100644
--- a/packages/svelte-querybuilder/src/lib/components/MatchModeEditor.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/MatchModeEditor.svelte
@@ -67,8 +67,8 @@
     listsAsArrays: false,
     path: dummyPath,
     level: 0,
-  }} />
-{#if requiresThreshold(props.match.mode)}
+  }} /><!--
+-->{#if requiresThreshold(props.match.mode)}
   <Control
     control={numericEditor}
     props={{
diff --git a/packages/svelte-querybuilder/src/lib/components/RuleComponents.svelte b/packages/svelte-querybuilder/src/lib/components/RuleComponents.svelte
index 2569734..85420ee 100644
--- a/packages/svelte-querybuilder/src/lib/components/RuleComponents.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/RuleComponents.svelte
@@ -1,12 +1,3 @@
-<!--
-  @component
-  The controls that make up a rule, without the wrapping `<div>`.
-
-  Port of React Query Builder's `RuleComponents`. In `subQuery` mode (used by
-  `RuleSubQuery.svelte`) the subquery's group header and body are rendered in `<div>`s around
-  the rule's own action buttons, which is why one instance has to hold two `(props, parts)`
-  pairs from two separate query-builder states.
--->
 <script lang="ts">
   import { TestID } from '@react-querybuilder/core';
   import Control from '../internal/Control.svelte';
@@ -341,41 +332,61 @@
   });
 </script>
 
+<!--
+  @component
+  The controls that make up a rule, without the wrapping `<div>`.
+
+  Port of React Query Builder's `RuleComponents`. In `subQuery` mode (used by
+  `RuleSubQuery.svelte`) the subquery's group header and body are rendered in `<div>`s around
+  the rule's own action buttons, which is why one instance has to hold two `(props, parts)`
+  pairs from two separate query-builder states.
+
+  The `<!-- -->`
+joiners between siblings are load-bearing, here and in every other component whose output lands
+inside a rule or group element. JSX drops whitespace-only lines between elements; Svelte collapses
+each gap to a single space and keeps it, which would put text nodes in the DOM that React Query
+Builder never emits. The conformance fixtures compare each element's own text verbatim, so the
+difference is a failure, not a nicety. Do not reformat these apart. -->
+
 {#if schema.showShiftActions}
   <Control control={controls.shiftActions} props={shiftActionsProps} />
-{/if}
-{#if parts.showFieldSelector}
+{/if}<!--
+-->{#if parts.showFieldSelector}
   <Control control={controls.fieldSelector} props={fieldSelectorProps} />
-{/if}
-{#if schema.autoSelectField || ruleObj.field !== translations.fields.placeholderName}
+{/if}<!--
+-->{#if schema.autoSelectField || ruleObj.field !== translations.fields.placeholderName}
   {#if mode === 'subQuery'}
     <Control control={controls.matchModeEditor} props={matchModeEditorProps} />
   {:else}
-    <Control control={controls.operatorSelector} props={operatorSelectorProps} />
-    {#if parts.showValueControls}
+    <Control
+      control={controls.operatorSelector}
+      props={operatorSelectorProps} /><!--
+    -->{#if parts.showValueControls}
       {#if parts.showValueSourceSelector}
         <Control control={controls.valueSourceSelector} props={valueSourceSelectorProps} />
-      {/if}
-      <Control control={controls.valueEditor} props={valueEditorProps} />
+      {/if}<!--
+      --><Control control={controls.valueEditor} props={valueEditorProps} />
     {/if}
   {/if}
-{/if}
-{#if subQuery}
+{/if}<!--
+-->{#if subQuery}
   <div class={subQuery.parts.classNames.header}>
     <RuleGroupHeader props={subQuery.props} parts={subQuery.parts} />
   </div>
-{/if}
-{#if schema.showCloneButtons}
+{/if}<!--
+-->{#if schema.showCloneButtons}
   <Control control={controls.cloneRuleAction} props={cloneRuleActionProps} />
-{/if}
-{#if schema.showLockButtons}
+{/if}<!--
+-->{#if schema.showLockButtons}
   <Control control={controls.lockRuleAction} props={lockRuleActionProps} />
-{/if}
-{#if schema.showMuteButtons}
+{/if}<!--
+-->{#if schema.showMuteButtons}
   <Control control={controls.muteRuleAction} props={muteRuleActionProps} />
-{/if}
-<Control control={controls.removeRuleAction} props={removeRuleActionProps} />
-{#if subQuery}
+{/if}<!--
+--><Control
+  control={controls.removeRuleAction}
+  props={removeRuleActionProps} /><!--
+-->{#if subQuery}
   <div class={subQuery.parts.classNames.body}>
     <RuleGroupBody props={subQuery.props} parts={subQuery.parts} />
   </div>
diff --git a/packages/svelte-querybuilder/src/lib/components/RuleGroup.svelte b/packages/svelte-querybuilder/src/lib/components/RuleGroup.svelte
index c0612f6..67a999f 100644
--- a/packages/svelte-querybuilder/src/lib/components/RuleGroup.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/RuleGroup.svelte
@@ -33,6 +33,8 @@
   <div class={parts.classNames.header}>
     <RuleGroupHeader {props} {parts} />
   </div>
+  <!--
+  -->
   <div class={parts.classNames.body}>
     <RuleGroupBody {props} {parts} />
   </div>
diff --git a/packages/svelte-querybuilder/src/lib/components/RuleGroupBody.svelte b/packages/svelte-querybuilder/src/lib/components/RuleGroupBody.svelte
index 4f50663..79f9cd3 100644
--- a/packages/svelte-querybuilder/src/lib/components/RuleGroupBody.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/RuleGroupBody.svelte
@@ -85,8 +85,8 @@
           return parts.disabled;
         },
       })} />
-  {/if}
-  {#if typeof r === 'string'}
+  {/if}<!--
+  -->{#if typeof r === 'string'}
     <Control
       control={controls.inlineCombinator}
       props={withCommonProps(inlineCommon, {
diff --git a/packages/svelte-querybuilder/src/lib/components/RuleGroupHeader.svelte b/packages/svelte-querybuilder/src/lib/components/RuleGroupHeader.svelte
index 5be6c34..df2df5c 100644
--- a/packages/svelte-querybuilder/src/lib/components/RuleGroupHeader.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/RuleGroupHeader.svelte
@@ -1,10 +1,3 @@
-<!--
-  @component
-  The controls in a rule group's header, without the wrapping `<div>`.
-
-  Port of React Query Builder's `RuleGroupHeaderComponents`. Internal rather than a control
-  element; it is a separate component only so that `Rule` can reuse it for a subquery.
--->
 <script lang="ts">
   import { TestID } from '@react-querybuilder/core';
   import Control from '../internal/Control.svelte';
@@ -291,31 +284,44 @@
   });
 </script>
 
+<!--
+  @component
+  The controls in a rule group's header, without the wrapping `<div>`.
+
+  Port of React Query Builder's `RuleGroupHeaderComponents`. Internal rather than a control
+  element; it is a separate component only so that `Rule` can reuse it for a subquery.
+
+  The `<!-- -->`
+joiners between siblings suppress the whitespace text nodes Svelte would otherwise emit between them
+— see `RuleComponents.svelte` for why that matters. -->
+
 {#if schema.showShiftActions && path.length > 0}
   <Control control={controls.shiftActions} props={shiftActionsProps} />
-{/if}
-{#if !schema.showCombinatorsBetweenRules && !schema.independentCombinators}
+{/if}<!--
+-->{#if !schema.showCombinatorsBetweenRules && !schema.independentCombinators}
   <Control control={controls.combinatorSelector} props={combinatorSelectorProps} />
-{/if}
-{#if schema.showNotToggle}
+{/if}<!--
+-->{#if schema.showNotToggle}
   <Control control={controls.notToggle} props={notToggleProps} />
-{/if}
-<Control control={controls.addRuleAction} props={addRuleActionProps} />
-{#if schema.maxLevels > path.length}
+{/if}<!--
+--><Control
+  control={controls.addRuleAction}
+  props={addRuleActionProps} /><!--
+-->{#if schema.maxLevels > path.length}
   <Control control={controls.addGroupAction} props={addGroupActionProps} />
-{/if}
-{#if schema.showCloneButtons && path.length > 0}
+{/if}<!--
+-->{#if schema.showCloneButtons && path.length > 0}
   <Control control={controls.cloneGroupAction} props={cloneGroupActionProps} />
-{/if}
-{#if schema.showLockButtons}
+{/if}<!--
+-->{#if schema.showLockButtons}
   <Control control={controls.lockGroupAction} props={lockGroupActionProps} />
-{/if}
-{#if schema.showMuteButtons}
+{/if}<!--
+-->{#if schema.showMuteButtons}
   <Control control={controls.muteGroupAction} props={muteGroupActionProps} />
-{/if}
-{#if schema.showUndoRedo && path.length === 0}
+{/if}<!--
+-->{#if schema.showUndoRedo && path.length === 0}
   <Control control={controls.undoRedoActions} props={undoRedoActionsProps} />
-{/if}
-{#if path.length > 0}
+{/if}<!--
+-->{#if path.length > 0}
   <Control control={controls.removeGroupAction} props={removeGroupActionProps} />
 {/if}
diff --git a/packages/svelte-querybuilder/src/lib/components/ShiftActions.svelte b/packages/svelte-querybuilder/src/lib/components/ShiftActions.svelte
index dd4907e..80c994e 100644
--- a/packages/svelte-querybuilder/src/lib/components/ShiftActions.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/ShiftActions.svelte
@@ -26,8 +26,9 @@
     type="button"
     disabled={disabled || shiftUpDisabled}
     onclick={e => shiftUp?.(e)}
-    title={titles?.shiftUp}><Label label={labels?.shiftUp} /></button>
-  <button
+    title={titles?.shiftUp}><Label label={labels?.shiftUp} /></button
+  ><!--
+  --><button
     type="button"
     disabled={disabled || shiftDownDisabled}
     onclick={e => shiftDown?.(e)}
diff --git a/packages/svelte-querybuilder/src/lib/components/ValueEditor.svelte b/packages/svelte-querybuilder/src/lib/components/ValueEditor.svelte
index e900ca5..4f83b16 100644
--- a/packages/svelte-querybuilder/src/lib/components/ValueEditor.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/ValueEditor.svelte
@@ -101,8 +101,8 @@
 {:else if isBetween}
   <span data-testid={props.testID} class={props.className} title={props.title}>
     {#each [0, 1] as i (i)}
-      {#if i === 1}{@render separator()}{/if}
-      {#if type === 'text'}
+      {#if i === 1}{@render separator()}{/if}<!--
+      -->{#if type === 'text'}
         <input
           type={inputTypeCoerced}
           placeholder={placeholderText}
@@ -171,8 +171,8 @@
           value={v.name}
           disabled={props.disabled}
           checked={props.value === v.name}
-          onchange={e => props.handleOnChange(e.currentTarget.value)} />
-        {v.label}
+          onchange={e => props.handleOnChange(e.currentTarget.value)} /><!--
+        -->{v.label}
       </label>
     {/each}
   </span>
diff --git a/packages/svelte-querybuilder/src/routes/+layout.svelte b/packages/svelte-querybuilder/src/routes/+layout.svelte
new file mode 100644
index 0000000..efb86dc
--- /dev/null
+++ b/packages/svelte-querybuilder/src/routes/+layout.svelte
@@ -0,0 +1,19 @@
+<!--
+  @component
+  Root layout for the development playground. Not published: `svelte-package` only reads
+  `src/lib`, so everything under `src/routes` exists solely to run the library against a real
+  SvelteKit app while developing it.
+
+  The stylesheets are imported from *source*, not from `dist`, so a change to
+  `src/lib/styles/_svelte.scss` hot-reloads without a `bun run build:css`.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import '@react-querybuilder/core/dist/query-builder.scss';
+  import '$lib/styles/_svelte.scss';
+  import './playground.css';
+
+  const { children }: { children: Snippet } = $props();
+</script>
+
+{@render children()}
diff --git a/examples/demo/src/App.svelte b/packages/svelte-querybuilder/src/routes/+page.svelte
similarity index 89%
rename from examples/demo/src/App.svelte
rename to packages/svelte-querybuilder/src/routes/+page.svelte
index 2b25a58..7b6a233 100644
--- a/examples/demo/src/App.svelte
+++ b/packages/svelte-querybuilder/src/routes/+page.svelte
@@ -6,13 +6,18 @@
     type FormatQueryOptions,
     type RuleGroupType,
     type RuleGroupTypeIC,
-  } from 'svelte-querybuilder';
+  } from '$lib/index.js';
 
   const fields: Field[] = [
     { name: 'firstName', label: 'First name', placeholder: 'Enter first name' },
     { name: 'lastName', label: 'Last name', placeholder: 'Enter last name' },
     { name: 'age', label: 'Age', inputType: 'number' },
-    { name: 'isMusician', label: 'Is a musician', valueEditorType: 'checkbox', defaultValue: false },
+    {
+      name: 'isMusician',
+      label: 'Is a musician',
+      valueEditorType: 'checkbox',
+      defaultValue: false,
+    },
     {
       name: 'instrument',
       label: 'Primary instrument',
@@ -119,16 +124,19 @@
   };
 </script>
 
-<h1>svelte-querybuilder demo</h1>
+<h1>svelte-querybuilder playground</h1>
 <p class="subtitle">
-  Running against library source. Edit anything under
-  <code>packages/svelte-querybuilder/src/lib</code> and this page hot-reloads.
+  Running against library source. Edit anything under <code>src/lib</code> and this page hot-reloads.
 </p>
 
 <div class="controls">
-  <label><input type="checkbox" bind:checked={independentCombinators} /> independent combinators</label>
+  <label
+    ><input type="checkbox" bind:checked={independentCombinators} /> independent combinators</label>
   <label>
-    <input type="checkbox" bind:checked={showCombinatorsBetweenRules} disabled={independentCombinators} />
+    <input
+      type="checkbox"
+      bind:checked={showCombinatorsBetweenRules}
+      disabled={independentCombinators} />
     showCombinatorsBetweenRules
   </label>
   <label><input type="checkbox" bind:checked={showNotToggle} /> showNotToggle</label>
diff --git a/examples/demo/src/app.css b/packages/svelte-querybuilder/src/routes/playground.css
similarity index 100%
rename from examples/demo/src/app.css
rename to packages/svelte-querybuilder/src/routes/playground.css
diff --git a/packages/svelte-querybuilder/svelte.config.js b/packages/svelte-querybuilder/svelte.config.js
index f94c05e..1afb067 100644
--- a/packages/svelte-querybuilder/svelte.config.js
+++ b/packages/svelte-querybuilder/svelte.config.js
@@ -1,10 +1,22 @@
+import adapter from '@sveltejs/adapter-node';
 import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
 
-/** @type {import('@sveltejs/vite-plugin-svelte').SvelteConfig} */
+/**
+ * SvelteKit config, but the Kit app is only the development playground under `src/routes` —
+ * `svelte-package` reads `src/lib` and ignores everything here except `preprocess` and
+ * `compilerOptions`.
+ *
+ * @type {import('@sveltejs/kit').Config}
+ */
 export default {
   preprocess: vitePreprocess(),
   compilerOptions: {
     // Runes-only components.
     runes: true,
   },
+  kit: {
+    // Pinned rather than `adapter-auto`; the playground is never deployed, so this exists only
+    // to keep `vite build` from failing on a missing adapter.
+    adapter: adapter(),
+  },
 };
diff --git a/packages/svelte-querybuilder/test/conformance/cases.ts b/packages/svelte-querybuilder/test/conformance/cases.ts
index 7c10050..fa1a818 100644
--- a/packages/svelte-querybuilder/test/conformance/cases.ts
+++ b/packages/svelte-querybuilder/test/conformance/cases.ts
@@ -8,7 +8,7 @@ import * as path from 'node:path';
 import { render } from '@testing-library/svelte';
 import { tick, type ComponentProps } from 'svelte';
 import { QueryBuilder } from '../../src/lib';
-import { extract, type ExtractResult } from './extract';
+import { extract, type ClassNameEntry, type ExtractResult } from './extract';
 import { queries, type QueryFixtureName } from './queries';
 import { scenarios, type Scenario } from './scenarios';
 
@@ -37,8 +37,27 @@ export const loadFixture = async <T>(name: string): Promise<T & FixtureMeta> =>
   }
 };
 
-/** One scenario × query pair, in the order `generate.tsx` flattened them. */
-export interface RenderPair {
+/** The first fixture schema that records the per-element `text` channel. */
+export const TEXT_CHANNEL_SCHEMA_VERSION = 3;
+
+/**
+ * Narrows extracted entries to the channels the loaded fixtures actually recorded.
+ *
+ * The extractor always emits `text`, because that is the shape upstream settled on. Fixtures
+ * older than `schemaVersion` 3 have no such key, and deep equality against them would fail on a
+ * channel they never claimed anything about — so it is dropped rather than asserted. Bumping
+ * `CONFORMANCE_TAG` to a release that publishes schema 3 turns the channel on with no further
+ * change here; review that first diff rather than suppressing it.
+ */
+export const stripUnrecordedChannels = (
+  entries: ClassNameEntry[],
+  { schemaVersion }: FixtureMeta
+): ClassNameEntry[] =>
+  schemaVersion >= TEXT_CHANNEL_SCHEMA_VERSION
+    ? entries
+    : entries.map(({ text: _text, ...rest }) => rest as ClassNameEntry);
+
+/** One scenario × query pair, in the order `generate.tsx` flattened them. */ export interface RenderPair {
   scenario: Scenario;
   queryName: string;
   query: unknown;
diff --git a/packages/svelte-querybuilder/test/conformance/classnames-post-flush.test.ts b/packages/svelte-querybuilder/test/conformance/classnames-post-flush.test.ts
index 7f7fcc7..3c644a2 100644
--- a/packages/svelte-querybuilder/test/conformance/classnames-post-flush.test.ts
+++ b/packages/svelte-querybuilder/test/conformance/classnames-post-flush.test.ts
@@ -15,7 +15,12 @@
 
 import { cleanup } from '@testing-library/svelte';
 import { afterEach, describe, expect, it } from 'vitest';
-import { loadFixture, renderAndExtractPostFlush, renderPairs } from './cases';
+import {
+  loadFixture,
+  renderAndExtractPostFlush,
+  renderPairs,
+  stripUnrecordedChannels,
+} from './cases';
 import type { ClassNameEntry } from './extract';
 
 interface PostFlushFixture {
@@ -57,14 +62,15 @@ describe('conformance: classnames (post-flush)', () => {
 
     it(`${expected.scenario} × ${expected.query}`, async () => {
       const { classNames } = await renderAndExtractPostFlush(pair);
+      const recorded = stripUnrecordedChannels(classNames, fixture);
 
-      expect(classNames).toEqual(expected.classNames);
+      expect(recorded).toEqual(expected.classNames);
 
       if (expected.differsFromStatic) {
         // A port that never runs its reset effect would pass both layers without this.
-        expect(classNames).not.toEqual(staticEntry.classNames);
+        expect(recorded).not.toEqual(staticEntry.classNames);
       } else {
-        expect(classNames).toEqual(staticEntry.classNames);
+        expect(recorded).toEqual(staticEntry.classNames);
       }
     });
   }
diff --git a/packages/svelte-querybuilder/test/conformance/classnames.test.ts b/packages/svelte-querybuilder/test/conformance/classnames.test.ts
index 3df1e45..a35e375 100644
--- a/packages/svelte-querybuilder/test/conformance/classnames.test.ts
+++ b/packages/svelte-querybuilder/test/conformance/classnames.test.ts
@@ -13,7 +13,7 @@
 
 import { cleanup } from '@testing-library/svelte';
 import { afterEach, describe, expect, it } from 'vitest';
-import { loadFixture, renderAndExtract, renderPairs } from './cases';
+import { loadFixture, renderAndExtract, renderPairs, stripUnrecordedChannels } from './cases';
 import type { ClassNameEntry } from './extract';
 import { scenarios } from './scenarios';
 
@@ -53,7 +53,7 @@ describe('conformance: classnames', () => {
     it(`${expected.scenario} × ${expected.query}`, () => {
       const { classNames } = renderAndExtract(pair);
 
-      expect(classNames).toEqual(expected.classNames);
+      expect(stripUnrecordedChannels(classNames, fixture)).toEqual(expected.classNames);
     });
   }
 });
diff --git a/packages/svelte-querybuilder/test/conformance/extract.ts b/packages/svelte-querybuilder/test/conformance/extract.ts
index 498ba77..14e3c59 100644
--- a/packages/svelte-querybuilder/test/conformance/extract.ts
+++ b/packages/svelte-querybuilder/test/conformance/extract.ts
@@ -23,6 +23,19 @@ export interface ClassNameEntry {
   path?: string;
   /** The verbatim `class` attribute. Whitespace is preserved; this is a byte-level claim. */
   className: string;
+  /**
+   * The concatenation of this element's *own* direct text-node children, verbatim — no trimming,
+   * no whitespace collapsing, no descendant text. `''` when the element has no direct text nodes
+   * (present rather than omitted, so the key set is stable across entries).
+   *
+   * Verbatim is the point: the drift this channel catches is a stray space inside a label or a
+   * whitespace text node emitted by a template compiler — exactly the SFC-whitespace hazard, and
+   * invisible under any normalization (jest-dom's `toHaveTextContent` included). Descendant text
+   * is deliberately excluded: `textContent` would repeat one label at every ancestor level.
+   *
+   * Recorded only by `schemaVersion` 3 fixtures; see `stripUnrecordedChannels` in `cases.ts`.
+   */
+  text: string;
 }
 
 /** The accessible description (`title`) of one rule group. */
@@ -65,6 +78,12 @@ export const extract = (container: Element): ExtractResult => {
         ...(testID === undefined ? {} : { testID }),
         ...(path === undefined ? {} : { path }),
         className,
+        // Direct text-node children only, in document order. `Node.TEXT_NODE` is spelled `3`
+        // rather than referenced off the constructor, matching upstream.
+        text: [...element.childNodes]
+          .filter(node => node.nodeType === 3)
+          .map(node => node.nodeValue ?? '')
+          .join(''),
       });
     }
 
diff --git a/packages/svelte-querybuilder/tsconfig.json b/packages/svelte-querybuilder/tsconfig.json
index c2ac93e..4ffb881 100644
--- a/packages/svelte-querybuilder/tsconfig.json
+++ b/packages/svelte-querybuilder/tsconfig.json
@@ -1,9 +1,26 @@
 {
-  "extends": "../../tsconfig.base.json",
+  // Extends the SvelteKit-generated config (run `svelte-kit sync` first, which `check` does),
+  // not `tsconfig.base.json` -- Kit owns `$lib`, `rootDirs`, and module resolution for the
+  // playground under `src/routes`. The options below restate the ones this monorepo cares
+  // about that Kit's generated config does not set.
+  "extends": "./.svelte-kit/tsconfig.json",
   "compilerOptions": {
+    "checkJs": true,
+    "declaration": true,
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    // `@react-querybuilder/core`'s declarations carry type-only imports of its optional
+    // integrations (`drizzle-orm`, `sequelize`, `@tanstack/db`), none of which are installed.
+    "skipLibCheck": true,
     "types": ["vitest/globals", "@testing-library/jest-dom", "bun"]
   },
+  // Kit's generated `include` covers `src` and its own generated types; the test harness and
+  // scripts live outside it and must be added back. Paths are relative to this file, whereas
+  // the inherited ones are relative to `.svelte-kit` -- hence the duplication.
   "include": [
+    ".svelte-kit/ambient.d.ts",
+    ".svelte-kit/non-ambient.d.ts",
+    ".svelte-kit/types/**/$types.d.ts",
     "src/**/*.ts",
     "src/**/*.js",
     "src/**/*.svelte",
diff --git a/packages/svelte-querybuilder/vite.config.ts b/packages/svelte-querybuilder/vite.config.ts
index 9c512dc..3c6bd69 100644
--- a/packages/svelte-querybuilder/vite.config.ts
+++ b/packages/svelte-querybuilder/vite.config.ts
@@ -1,25 +1,14 @@
-import { svelte } from '@sveltejs/vite-plugin-svelte';
-import { svelteTesting } from '@testing-library/svelte/vite';
-import { defineConfig } from 'vitest/config';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
 
+/**
+ * Serves the development playground under `src/routes`. Nothing published goes through here —
+ * `svelte-package` reads `src/lib` directly.
+ *
+ * The test runner deliberately does *not* share this config: `sveltekit()` resolves the Kit
+ * project relative to the process's working directory, which is the monorepo root when Vitest
+ * runs the package as a `projects` entry. See `vitest.config.ts`.
+ */
 export default defineConfig({
-  plugins: [svelte(), svelteTesting()],
-  test: {
-    environment: 'jsdom',
-    globals: true,
-    include: ['src/**/*.{test,spec}.ts'],
-    setupFiles: ['./vitest-setup.ts'],
-    // Must live here, not in the root config: root-level `test` options are NOT inherited by
-    // `projects` configs, which is how CI runs the suite. (`coverage` is the exception and goes
-    // the other way — see the note in the root `vitest.config.ts`.)
-    //
-    // The a11y suite is the slowest in the repo and CI runners are 2-core, so the 5s default is
-    // too tight even though no single case is near this. Headroom, not a budget.
-    testTimeout: 15_000,
-    coverage: {
-      provider: 'v8',
-      include: ['src/lib/**'],
-      thresholds: { lines: 80 },
-    },
-  },
+  plugins: [sveltekit()],
 });
diff --git a/packages/svelte-querybuilder/vitest.config.ts b/packages/svelte-querybuilder/vitest.config.ts
new file mode 100644
index 0000000..a77f8b0
--- /dev/null
+++ b/packages/svelte-querybuilder/vitest.config.ts
@@ -0,0 +1,31 @@
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import { svelteTesting } from '@testing-library/svelte/vite';
+import { defineConfig } from 'vitest/config';
+
+/**
+ * The unit suite, on the bare `svelte()` plugin rather than `sveltekit()`. Tests import the
+ * library by relative path and need nothing from Kit, and the Kit plugin resolves its project
+ * from `process.cwd()` — which is the monorepo root when the root config runs this package as a
+ * `projects` entry, so it would look for `src/app.html` in the wrong place.
+ */
+export default defineConfig({
+  plugins: [svelte(), svelteTesting()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    include: ['src/**/*.{test,spec}.ts'],
+    setupFiles: ['./vitest-setup.ts'],
+    // Must live here, not in the root config: root-level `test` options are NOT inherited by
+    // `projects` configs, which is how CI runs the suite. (`coverage` is the exception and goes
+    // the other way — see the note in the root `vitest.config.ts`.)
+    //
+    // The a11y suite is the slowest in the repo and CI runners are 2-core, so the 5s default is
+    // too tight even though no single case is near this. Headroom, not a budget.
+    testTimeout: 15_000,
+    coverage: {
+      provider: 'v8',
+      include: ['src/lib/**'],
+      thresholds: { lines: 80 },
+    },
+  },
+});
diff --git a/vitest.config.ts b/vitest.config.ts
index e831485..7657899 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -2,7 +2,7 @@ import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
   test: {
-    projects: ['packages/*/vite.config.ts'],
+    projects: ['packages/*/vitest.config.ts'],
     // Coverage is resolved from the root config only; the identical block in the package's
     // `vite.config.ts` is inert when the suite runs through `projects`, which is how CI runs it.
     coverage: {

From 40e437b58b6952b07a770eb983df30b1e8477d1e Mon Sep 17 00:00:00 2001
From: Jake Boone <jakeboone02@gmail.com>
Date: Thu, 13 Aug 2026 17:19:27 -0700
Subject: [PATCH 3/3] Address PR comments

---
 AGENTS.md                                            |  2 +-
 .../src/lib/components/RuleComponents.svelte         | 12 ++++++------
 .../src/lib/components/RuleGroupHeader.svelte        |  5 ++---
 3 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5e8ed50..c1cb19c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -93,7 +93,7 @@ Runes only. No Svelte 4 idioms — no `export let`, no `$:`, no stores for compo
 
 ```svelte
 <script lang="ts">
-  import type { QueryBuilderProps } from './types';
+  import type { QueryBuilderProps } from './types/index.js';
 
   let { fields, query = $bindable(), onQueryChange }: QueryBuilderProps = $props();
 
diff --git a/packages/svelte-querybuilder/src/lib/components/RuleComponents.svelte b/packages/svelte-querybuilder/src/lib/components/RuleComponents.svelte
index 85420ee..2065e58 100644
--- a/packages/svelte-querybuilder/src/lib/components/RuleComponents.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/RuleComponents.svelte
@@ -341,12 +341,12 @@
   the rule's own action buttons, which is why one instance has to hold two `(props, parts)`
   pairs from two separate query-builder states.
 
-  The `<!-- -->`
-joiners between siblings are load-bearing, here and in every other component whose output lands
-inside a rule or group element. JSX drops whitespace-only lines between elements; Svelte collapses
-each gap to a single space and keeps it, which would put text nodes in the DOM that React Query
-Builder never emits. The conformance fixtures compare each element's own text verbatim, so the
-difference is a failure, not a nicety. Do not reformat these apart. -->
+  The empty-HTML-comment joiners between siblings are load-bearing, here and in every other
+  component whose output lands inside a rule or group element. JSX drops whitespace-only lines
+  between elements; Svelte collapses each gap to a single space and keeps it, which would put text
+  nodes in the DOM that React Query Builder never emits. The conformance fixtures compare each
+  element's own text verbatim, so the difference is a failure, not a nicety. Do not reformat these
+  apart. -->
 
 {#if schema.showShiftActions}
   <Control control={controls.shiftActions} props={shiftActionsProps} />
diff --git a/packages/svelte-querybuilder/src/lib/components/RuleGroupHeader.svelte b/packages/svelte-querybuilder/src/lib/components/RuleGroupHeader.svelte
index df2df5c..e1a942a 100644
--- a/packages/svelte-querybuilder/src/lib/components/RuleGroupHeader.svelte
+++ b/packages/svelte-querybuilder/src/lib/components/RuleGroupHeader.svelte
@@ -291,9 +291,8 @@
   Port of React Query Builder's `RuleGroupHeaderComponents`. Internal rather than a control
   element; it is a separate component only so that `Rule` can reuse it for a subquery.
 
-  The `<!-- -->`
-joiners between siblings suppress the whitespace text nodes Svelte would otherwise emit between them
-— see `RuleComponents.svelte` for why that matters. -->
+  The empty-HTML-comment joiners between siblings suppress the whitespace text nodes Svelte would
+  otherwise emit between them — see `RuleComponents.svelte` for why that matters. -->
 
 {#if schema.showShiftActions && path.length > 0}
   <Control control={controls.shiftActions} props={shiftActionsProps} />