@mohsinonxrm/pptb-fetchxml-studio 1.4.2 → 1.5.0-beta.12

package/CHANGELOG.md

@@ -7,6 +7,251 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0-beta.12] - 2026-10-18
+
+### ✨ Added
+
+- **Saved views follow-ups (#142):**
+  - **Shared personal views:** Load view shows "Shared by {owner}" (or "Shared with you"). System views show their query type or "Default view" as a second line.
+  - **Write access:** before overwriting a personal view you don't own, Save view checks your access (`RetrievePrincipalAccess`). Without write access, it offers **Save a copy…**; if access can't be determined, Dataverse decides.
+  - **Managed system views:** overwriting one shows a warning naming its solution. It's a warning only, not a block.
+  - **Quick find views:** enter a test value for `{0}`, with an optional trailing `%`, to execute them. The value is used only in the FetchXML that runs; the tree, the editor and saved views keep `{0}`. A loaded quick find view runs as FetchXML, not by ID, because by ID it matches nothing (verified live).
+  - **Set as default view** for public system views.
+  - **Description:** pre-filled when you overwrite a view, and clearing it clears the view's description.
+- **Docs-driven helpers (#98):**
+  - **Wildcard helper** for `like` / `not-like` values: Contains (`%x%`), Begins with (`x%`), Ends with (`%x`) or a custom pattern. **Match literally** escapes `%` → `[%]`, `_` → `[_]` and `[` → `[[]`, per "Wildcard characters".
+    - begins-with and ends-with warn when a typed character would act as a wildcard.
+    - Stored values read back into the helper, and switching operators keeps the text.
+    - The Query Advisor's leading-wildcard advice ignores escaped characters, and now also appears in the results-grid column filter.
+  - **Total record count:** with *Return total record count*, the info bar shows "Rows: 50 of 1,234 total", or "5,000+ total" (500+ on elastic entities) when the limit is exceeded. **Count all {entity} records (unfiltered snapshot)** calls `RetrieveTotalRecordCount` and says plainly that it ignores the query's filters.
+  - **Hierarchy picker:** under / not-under / above / eq-or-under / eq-or-above on the primary key pick a record by name (`startswith` search, so no leading wildcard). The record's name is resolved back from its ID, and **Enter an ID instead** gives a GUID field with validation. The hint names the hierarchical relationship and the 100-level limit.
+  - **GUID values:** Lookup, Customer, Owner and Uniqueidentifier condition values that aren't GUIDs are flagged. Verified live: Dataverse rejects them with 0x80040203.
+  - **Undocumented settings:** "UTC offset (undocumented)" shows only when the query sets it, and the condition aggregate leftover reads "Aggregate (undocumented)".
+
+### 🔧 Fixed
+
+- **Record actions use the current selection after the results refresh (#158).** Previously, after a refresh (re-running the query, or the automatic refresh after Delete, Activate or Run workflow), the grid showed nothing selected, but the command bar kept the previous selection. Its actions stayed enabled and ran on the previously selected records. The command bar now clears its selection with the grid's.
+
+### 🏗️ Technical
+
+- **Release process (`RELEASING.md`):** `main` holds the current stable release (npm `latest`); betas are tagged on `dev` (npm `beta`, GitHub pre-release); hotfixes branch from `main` and merge back into `dev`. PRs add CHANGELOG entries under `[Unreleased]` and don't change the version, which is set when a release is cut. The same process applies to Command Bar Studio and Dataverse Request Studio.
+- **`release.yml` refuses a stable tag whose commit isn't on `main`,** so a stray tag on `dev` can't replace npm `latest`. Beta tags (`-beta.N`) are allowed from `dev`.
+
+## [1.5.0-beta.11] - 2026-10-17
+
+### ✨ Added
+
+- **Activate and Deactivate work, driven by metadata (#143, verified live on temporary records).**
+  - **Simple entities** (Account, Contact…): the state's default status reason is applied.
+  - **Multi-state entities** (Lead, activities, custom state models): you pick the status reason, grouped by state. When the entity enforces status-reason transitions, only targets allowed from every selected record's current status are offered.
+  - **Lead:** Deactivate defaults to Disqualified. Choosing Qualified warns that this doesn't run QualifyLead; Dataverse accepts the plain update.
+  - **Opportunity, Case, Quote, Order, Invoice and Contract** close through their own messages (WinOpportunity / LoseOpportunity, CloseIncident, WinQuote, FulfillSalesOrder…). For these the buttons are disabled, with a tooltip naming the documented action. Proper dialogs are tracked in #149.
+  - **Also disabled, with a reason:** entities with no state, results with one-to-many joins, and missing Write privilege. The Write privilege name comes from metadata, e.g. `prvWriteActivity` for activities.
+  - **How it runs:** a PATCH of `statecode` + `statuscode`, sent through `$batch` in chunks of 25, with per-record errors, throttle retry, progress and the close warning. The query runs again afterwards.
+- **Confirmations name the environment and the scope (#69, Marketplace policy).** Delete, Bulk delete, Run workflow, Save view and Activate/Deactivate show:
+  - the environment name, type and URL, with a warning for **Production**;
+  - the entity's display and logical name;
+  - the exact scope. A Bulk delete with no selection says "Every record the query matches" and never claims a total it doesn't know.
+
+  **Type-to-confirm:** on Production, for more than 100 records, or when the total is unknown, you type the entity's logical name before the action enables.
+
+### 🔧 Fixed
+
+- **Bulk delete no longer shows a stray horizontal scrollbar (#152).** The "Danger zone" warning was 1px wider than the dialog, a grid item's default `min-width`. Its title now reads "Bulk delete all matching {entity}" or "Bulk delete N records".
+
+### 🔧 Changed
+
+- **Sentence case** in the delete, bulk delete, workflow and save view dialogs and the results command bar, completing the sweep from beta.10: Delete record, Run workflow, Save and publish, Personal view, Bulk delete (job), Delete all, Retrieve all stopped.
+
+### 🏗️ Technical
+
+- New `model/recordState.ts` (state planning from metadata, transition intersection, close-message entities) and `shared/components/TargetScope.tsx` with `targetScopeRules.ts`, all with tests.
+- The `$batch` runner in `batchDelete.ts` is shared by delete and the state update.
+
+## [1.5.0-beta.10] - 2026-10-17
+
+### ✨ Added
+
+- **Collapsible query scope section (#25).** It collapses to one line, "**Account** · View: Active accounts · Contoso Core", with **New** always visible. The collapsed state is remembered.
+- **The publisher and solution selection is remembered per environment (#25),** keyed by environment URL in the ToolBox settings. It's restored once the lists load; publishers or solutions that no longer exist are dropped.
+- **Right-click a tree row (#24).** Right-click, Shift+F10 or the context-menu key opens the row's Add items, a divider, then **Delete** in red. The root entity has no Delete.
+
+### 🔧 Changed
+
+- **Tree (#24, #25):**
+  - The Add menus are reordered, renamed and given the tree's icons: All attributes, **Select attributes…** (now second), **Blank attribute**, Order by, Filter, Link-entity.
+  - Deleting a node with items inside asks first: "Delete filter (and)? This also deletes the 2 items inside it."
+  - Rows with nothing inside have no chevron.
+  - A link-entity that can return attributes but has none shows "(no attributes)".
+  - A link-entity without an alias is labelled by its lookup, e.g. "contact via primarycontactid (outer)". The lookup is `to` for N:1 and `from` for 1:N.
+- **Relationship picker (#25):** each option has two lines, the related entity, then "via {lookup} ({logical}) · {schema name}". The groups are Many-to-one, One-to-many and Many-to-many, search matches any part, and the list is wide enough that options stay on two lines.
+- **Publishers and solutions (#25)** show two lines: name, then `uniquename · vX` for solutions and `uniquename · prefix` for publishers. The empty states are worded consistently.
+- **Sentence case and "…" across the UI,** matching Dataverse Request Studio and Command Bar Studio. For example: Load view, System views, Entity source, All entities, Advanced Find only, Use logical names, Editor mode, Parse to tree, Send to tool, Save as….
+
+### 🏗️ Technical
+
+- New `model/scopeSelection.ts`, `model/treeLabels.ts` and `model/relationshipOptions.ts`, and the `useRememberedScope` hook, with tests.
+
+## [1.5.0-beta.9] - 2026-10-17
+
+### 🏗️ Technical
+
+- **monaco-editor 0.54 → 0.57 (#145)** clears the moderate `dompurify` advisories.
+  - `@monaco-editor/react` stays at 4.7.0, because 4.8 is still a prerelease. An ambient type declaration maps its `editor.api` import to Monaco 0.57's `monaco-editor/editor` entry.
+  - **Smaller bundle:** Monaco loads only the editor core, its features and the languages FXS shows (XML, C#, JavaScript, shell and SQL), using the tree-shakeable entry points added in Monaco 0.56. With the full 0.57 entry, the package would have exceeded its size budget. Now it's 13 files instead of 98, and slightly smaller overall.
+  - **No worker console errors:** the editor worker runs on the main thread from the start, as before (PPTB's CSP blocks `blob:` workers), without the errors Monaco 0.57 would log first.
+  - **Remaining audit findings:** two low `dompurify` advisories (fixed in 3.4.16). Monaco bundles its own copy and doesn't use the affected `IN_PLACE` mode.
+- **`uuid` for exceljs pinned to 11.1.1 with an npm override (#145, GHSA-w5hq-g745-h8pq).** The browser build of exceljs bundles its own uuid and only calls `v4()`, so the advisory never applied to the tool.
+- **A round-trip test for local Excel export:** headers, typed values, formats, dates, labels, the "both" (Raw) columns, the frozen header and auto-filter.
+
+## [1.5.0-beta.8] - 2026-10-17
+
+### ✨ Added
+
+- **Query Advisor (#97).** Before you run a query, FetchXML Studio flags the performance anti-patterns Microsoft Learn documents, as notes in Validate, Parse to Tree and the property panel. **Advice never blocks Execute.** It covers:
+  - leading wildcards in `like` / `begins-with` values, and `ends-with`;
+  - `<all-attributes />` or no attributes selected;
+  - sorting by a link-entity's attributes, which is slower and can lose the paging cookie;
+  - `distinct` without an order;
+  - simple paging past 50,000 records;
+  - aggregate queries with no filter (the 50,000-record aggregate limit);
+  - the legacy `no-lock`.
+- **Query limits, verified live (#97):**
+  - **More than 15 joined link-entities** blocks Execute (0x8004430D). Link-entities inside filters don't count.
+  - **More than 500 conditions** blocks Execute (0x8004430C). Microsoft Learn says conditions and link-entities count together, but live, only conditions count: 500 conditions plus a link-entity run.
+  - **URL-encoded FetchXML over 32,768 characters** gets a warning with "Execute anyway". Live, about 44,500 characters failed with HTTP 414, but the exact limit depends on the URL.
+
+### 🏗️ Technical
+
+- New `model/queryAdvisor.ts`, called from `validateQueryRules`, with 91 table-driven tests. Every advice case is also checked to block nothing.
+- The condition Operator and Value fields, the aggregate and distinct options and the order Attribute field now show their advice notes, through the existing `findingFor`.
+
+## [1.5.0-beta.7] - 2026-10-17
+
+### 🔧 Fixed
+
+- **Load View labels querytype 2048 as "Other"** (`SavedQueryTypeOther`). It used to read "Template", a label that belongs to the template types (#144).
+- **PPTB events no longer log their payloads to the console (#71).** Connection events carry environment details. Event names are logged only when debug logging is on.
+
+### 🏗️ Technical
+
+- **Safe OData literals (#81).** Every value placed inside a single-quoted OData string literal now has its quotes doubled (`odataString`). That covers entity and attribute names in metadata queries, solution unique names, and the workflow and view filters. A value can no longer end the literal early.
+- **The duplicate LayoutXML helpers are removed from `pptbClient.ts` (#81).** They were unused; `model/layoutxml.ts` is the only implementation.
+
+## [1.5.0-beta.6] - 2026-10-17
+
+### 🔧 Fixed
+
+- **Column headers for one-to-many link-entities name the related entity (verified live).**
+  - A 1:N link-entity's column read "Full Name (Account)": the header used the parent's primary key, which is the link's `to` attribute.
+  - It now reads "Full Name (Contact)". The entity's display name comes from the cached entity lists, so it's there before the entity has been opened.
+  - N:1 columns are unchanged and still name the lookup ("Full Name (Primary Contact)").
+
+## [1.5.0-beta.5] - 2026-10-17
+
+### 🏗️ Technical
+
+- **Browser dev harness against a live org: `npm run dev:harness` (#78), modelled on Command Bar Studio #44.**
+  - **What it runs:** the real UI, in a browser, against the Dataverse org in `DATAVERSE_URL`.
+  - **How requests flow:**
+    - A stub of the PPTB host makes requests the same way PPTB 1.2.7 does: the same entity-set names, `execute()` encoding, Prefer headers and error text, plus optional `CallerObjectId` impersonation.
+    - A localhost-only Vite proxy attaches an Azure CLI token on the server side. The token is kept in memory only and is never logged or sent to the browser.
+    - The proxy only accepts requests from localhost with a harness header, and forwards only to the org's Web API over https.
+  - **Not shipped:** the harness is dev-only. The production build is byte-identical without it, and it isn't in the package. See `dev/README.md`.
+- **Dev tooling updated, clearing every high npm audit finding (#77):**
+  - versions: vite 7.3.6, @vitejs/plugin-react 5.2.0, typescript-eslint 8.71.0, eslint 9.39.5, plus transitive fixes (rollup, postcss and others);
+  - audit: 25 findings (17 high) → 4 moderate, 0 high;
+  - every changed package was published at least two weeks ago;
+  - no runtime dependencies changed.
+  - **Not bumped:** monaco-editor 0.57. Its `exports` map breaks `@monaco-editor/react` 4.7's types, so it needs its own change.
+
+## [1.5.0-beta.4] - 2026-10-17
+
+### ⚠️ Requires Power Platform ToolBox 1.2.7
+
+- **PPTB 1.2.7 is now required (#82).**
+  - `@pptb/types` is 1.2.7.
+  - `features.connections: 1`, and `minAPI` is 1.2.7 (it was 1.2.2).
+  - Older hosts and `1.2.7-dev` Insider builds show the tool as unsupported.
+
+### ✨ Added
+
+- **Changing the tool's connection in place resets everything that came from the old environment (#66).**
+  - The metadata cache, entity lists, publishers and solutions, privileges, WhoAmI, results and the loaded view are all cleared, and the UI reloads for the new connection. The query is kept.
+  - A notification says what happened.
+  - Token refreshes and edits to other connections reset nothing. Deleting another connection no longer marks the tool as disconnected.
+  - Workflow runs and multi-record deletes stop if the connection changes partway through.
+- **The ToolBox warns before closing while work is running (#70):** Retrieve All, deletes, workflow runs and Save view (`preventClose`).
+- **Record links open in the connection's browser profile (#70).** This covers Open record and the bulk delete job link (`openInConnectionBrowser`).
+
+### 🔧 Fixed
+
+- **Deleting records uses the entity's metadata entity set name (#61).** This fixes entities whose entity set name the host guesses wrongly.
+  - Multi-record deletes are sent as real OData `$batch` requests of 25 (`executeBatch`).
+  - Errors are reported per record: a batch Dataverse rejects is retried one record at a time, so one failure doesn't fail the rest.
+- **Clipboard writes try the ToolBox first (#70),** then the browser clipboard. That applies to copying results, record URLs, FetchXML and code.
+
+### 🏗️ Technical
+
+- New `api/host.ts` adapter. Every host API is feature-detected, with a fallback.
+- New `api/batchDelete.ts` and `shared/hooks/connectionIdentity.ts`.
+- `metadataCache.clear()` now clears every cache, with a generation guard so requests still running for the old connection can't refill it.
+
+## [1.5.0-beta.3] - 2026-10-17
+
+### ✨ Added
+
+- **Dataverse errors explain what to do (#96).** For documented error codes, the error bar, paging notices, export, delete, bulk delete, workflow and Save view messages start with what to do. Dataverse's own message follows after "Details:". Undocumented codes are shown unchanged. Covered:
+  - service protection limits (429, 0x80072322/21/26);
+  - the 50,000-record aggregate limit (0x8004E023);
+  - the quick find record limit;
+  - more than 500 conditions or 15 link-entities;
+  - query throttling and timeouts caused by leading wildcards, calculated attributes or other anti-patterns;
+  - aggregate mistakes;
+  - invalid condition values;
+  - missing attributes or entities;
+  - entity set names Web API doesn't recognise;
+  - records not found;
+  - missing privileges.
+- **Throttling back-off (#96).** When Dataverse service protection limits are hit, deletes, workflow runs and page loads wait and retry: per `Retry-After` when it's given, otherwise 2, 4 and 8 seconds. Each wait is capped at 60 seconds, with at most 3 retries.
+- **Pages over Power Platform ToolBox's 16 MB response limit (#68).**
+  - **Load more and Retrieve All:** the page is requested again at half the size, at most three times and never below 100 rows. The pages that follow keep the smaller size.
+  - **The first page and saved views:** the error explains how to make the response smaller (fewer attributes, or a smaller `count`), and nothing is retried.
+
+### 🔧 Changed
+
+- **Fewer startup calls and a quiet console (#71).**
+  - WhoAmI and each privilege check are sent once per connection, and concurrent callers share one request.
+  - Raw query results, privilege responses, payloads and routine status no longer go to the console. They're behind the debug flags (`src/shared/utils/debug.ts`), which are now all off by default.
+  - The Electron IPC prefix is removed from errors shown to users.
+
+### 🏗️ Technical
+
+- New modules, each with tests:
+  - `api/dataverseErrors.ts`: reads the PPTB 1.2.7 host's error formats and maps documented codes to Microsoft Learn;
+  - `api/throttleRetry.ts`;
+  - `api/sessionCache.ts`: `resetDataverseSessionCache()`, to be called on a connection change (#66);
+  - `api/pageRecovery.ts`.
+
+## [1.5.0-beta.2] - 2026-10-17
+
+### 📝 Documentation
+
+- **README: "What this tool changes" (#69, Marketplace policy).** Lists every operation that writes to Dataverse: Delete, Bulk Delete, Run workflow, and saving personal and system views. For each it says when it runs, what it does and which privilege it needs. It also lists what doesn't write: both exports and the locally stored settings.
+  - It states plainly that Delete with no rows selected submits a Bulk Delete job for every record the query matches, not just the loaded rows.
+
+## [1.5.0-beta.1] - 2026-10-17
+
+### 🔧 Fixed
+
+- **Cross-apply columns stay filled when they're filtered (#91 follow-up, verified live).**
+  - A `matchfirstrowusingcrossapply` link-entity normally returns its attributes by schema name (`FullName`).
+  - A condition with `entityname` targeting that link-entity, such as a column filter from the grid, makes Dataverse join it normally. It then returns `mc.fullname` instead.
+  - The grid now uses whichever key Dataverse returned, including for cross-apply `<all-attributes />`, so a filtered cross-apply column no longer shows as empty.
+- **Two cross-apply queries Dataverse rejects are now flagged before they run (verified live 2026-10-17).**
+  - An order inside a `matchfirstrowusingcrossapply` link-entity (0x80041121). Order from the entity with `entityname` instead; that works.
+  - An aliased attribute in one, which fails with a generic SQL error (0x80044150) unless a condition with `entityname` targets the link-entity. With such a condition the alias works, so that case isn't flagged.
+
 ## [1.4.2] - 2026-10-17
 
 The v1.4.2 milestone: the features other users asked for, a results grid that works from the query, saved views that behave as documented, operators that follow the docs, and the CI/CD and release setup shared with Command Bar Studio and Dataverse Request Studio. It was iterated through `1.4.2-beta.1` to `1.4.2-beta.7` (detailed below). Behaviour follows Microsoft Learn and the live operator matrix. Valid FetchXML is never refused, and a Dataverse error is shown as it is.

package/README.md

@@ -2,7 +2,7 @@
 
 A powerful, modern FetchXML query builder and data explorer for [Power Platform ToolBox](https://github.com/PowerPlatformToolBox/desktop-app). Inspired by the XrmToolBox FetchXML Builder, reimagined with React 18, Fluent UI v9, and seamless Dataverse integration.
 
-![Version](https://img.shields.io/badge/version-1.4.2-blue)
+![Version](https://img.shields.io/badge/version-1.5.0--beta.12-blue)
 [![npm](https://img.shields.io/npm/v/@mohsinonxrm/pptb-fetchxml-studio?label=npm)](https://www.npmjs.com/package/@mohsinonxrm/pptb-fetchxml-studio)
 ![React](https://img.shields.io/badge/React-18-61DAFB?logo=react)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript)
@@ -13,18 +13,23 @@ A powerful, modern FetchXML query builder and data explorer for [Power Platform
 
 ### 🔧 Visual Query Builder
 - **Tree-based hierarchy** — Build FetchXML queries visually with entities, attributes, filters, orders, and link-entities
+  - **Add menus and right-click** — Each row's + menu offers All attributes, Select attributes…, Blank attribute, Order by, Filter and Link-entity, with the tree's icons. Right-click (or Shift+F10) a row for the same items plus **Delete**. Deleting a node with items inside asks first.
+  - **Readable rows** — Rows with nothing inside have no chevron. A link-entity that can return attributes but has none says "(no attributes)". A link-entity without an alias is labelled by its lookup, e.g. "contact via primarycontactid (outer)".
+- **Query scope** — Publishers, Solutions, Entity and Load view sit in a section that collapses to one line (entity · view · solutions), with **New** always visible. Your publisher and solution selection is remembered for each environment. Solutions show their unique name and version, grouped Unmanaged / Managed.
 - **Property panel for every node** — Fetch options, entity, attributes, all-attributes, sorts, filters, conditions and link-entities each have an editor covering the full FetchXML reference. Every field explains itself in an info popover with a link to Microsoft Learn.
+  - **Docs-driven helpers** — Like / begins-with / ends-with values have a wildcard helper: Contains, Begins with, Ends with or a custom pattern, plus "Match literally", which escapes `%`, `_` and `[`. Hierarchy operators (under, above…) pick a record by name, with a Record ID fallback. Undocumented settings (UTC offset, condition aggregate) are labelled as such.
   - **Metadata-driven** — Attribute pickers, operators, value pickers, aggregate functions, date grouping, sortable attributes and compare-to-attribute choices follow each attribute's metadata, so the panel only offers what Dataverse accepts.
   - **Shows problems where they are** — Rule errors appear on the field they're about and as an **Error** badge in the tree; settings Dataverse ignores are listed with a **Remove** button.
   - **Tree badges** — Aggregate, Distinct, Retained and Hints on the query; Group by, date grouping and aggregate functions on attributes; Union and Quick find on filters.
   - **Safe mode changes** — Turning off aggregate, or switching a link-entity to a type that returns no attributes, lists what has to change and asks first.
 - **Full FetchXML support** — Aggregate queries, grouping, distinct, top/count, paging, and advanced hints
 - **Nested filters** — Create complex AND/OR filter groups with unlimited nesting
-- **Link-entity relationships** — Browse and add 1:N, N:1, and N:N relationships with inner/outer joins; N:N relationships join through their intersect entity, as documented; intersect entities (such as `systemuserroles` or `teammembership`) can be joined to each side of their N:N relationship
+- **Link-entity relationships** — Browse and add 1:N, N:1, and N:N relationships with inner/outer joins. Each option shows the related entity, then "via {lookup} · {schema name}", and search matches any part; N:N relationships join through their intersect entity, as documented; intersect entities (such as `systemuserroles` or `teammembership`) can be joined to each side of their N:N relationship
 
 ### 📊 Results Grid
 - **Virtualized DataGrid** — Handle large result sets with smooth scrolling (powered by react-window)
 - **Copy results** — Right-click a cell to copy its value, its raw value (GUID, number, ISO date or option value), the row, the selected rows or the column. **Ctrl+C** copies the selected rows, or the focused cell. The command bar's **Copy** menu copies the selected or all loaded rows, as shown or as raw values. Rows copy as tab-separated values with a header row, so they paste into Excel as cells
+- **Total record count** — With *Return total record count*, the info bar shows "Rows: 50 of 1,234 total", or "5,000+ total" when Dataverse caps the count. **Count all {entity} records** then gets the entity's unfiltered total (`RetrieveTotalRecordCount`, a snapshot that ignores the query's filters)
 - **Paging and Retrieve All** — Scrolling to the end loads the next page; **Retrieve All** loads every page, with **Stop** to keep what's loaded so far. Pages use the documented paging cookie and the query's own `count` and starting `page`. Queries Dataverse returns no cookie for (sorted by a link-entity attribute, or distinct) page by page number, with a note. Views follow `@odata.nextLink`. A failed page shows how many rows loaded, with **Retry**
 - **Rich cell rendering** — Power Apps-style display for lookups, option sets, dates, currency, and more
 - **Column header menu** — Click a header for **Sort** (A to Z, smallest to largest or oldest to newest, by type), **Filter by…** and **Clear filter**. Shift+click a header still adds it to a multi-column sort.
@@ -70,9 +75,13 @@ A powerful, modern FetchXML query builder and data explorer for [Power Platform
 - **LayoutXML preview** — See the column layout configuration
 
 ### 📥 Load & Save Views
-- **Load system/personal views** — Browse and load existing Dataverse views
-- **Optimized view execution** — Uses SavedQuery/UserQuery APIs for better performance
-- **Save to Dataverse** — Save your queries as new personal views or update existing ones
+- **Load system/personal views** — Browse and load existing Dataverse views of every query type. Personal views shared with you show "Shared by {owner}", and system views show their type or "Default view"
+- **Optimized view execution** — An unmodified loaded view runs by its ID (SavedQuery/UserQuery). Quick find views run as FetchXML with the test value you enter for `{0}`; the query keeps `{0}`
+- **Save to Dataverse** — Save your queries as new personal or system views, or update existing ones.
+  - Before overwriting a shared personal view, your write access is checked; without it you get **Save a copy…**.
+  - Overwriting a managed system view warns first.
+  - Public system views can be **set as the default view**.
+  - The description is pre-filled.
 - **Solution-aware** — Add views to solutions during save
 
 ### 📤 Export & Data Operations
@@ -123,6 +132,24 @@ A powerful, modern FetchXML query builder and data explorer for [Power Platform
 - **Workflow privilege check** — Validates `prvReadWorkflow` + `prvWorkflowExecution` before showing workflow picker
 - **View save privilege check** — Validates `prvWriteQuery` / `prvWriteCustomization` / `prvPublishCustomization` / `prvWriteUserQuery` before save operations
 
+## ✏️ What this tool changes
+
+FetchXML Studio only reads from Dataverse until you start one of the operations below. Each one asks for confirmation first, and the confirmation names the target: the environment (connection name, URL and type, with Production highlighted), the entity, and how many records (or which view). For the record operations, on a Production connection, for more than 100 records, or when the total isn't known (Bulk Delete with no rows selected), you type the entity logical name before the button enables. They all run as the connected user, or as the user PPTB is impersonating, so Dataverse applies that user's security roles.
+
+| Operation | When | What it does in Dataverse |
+|---|---|---|
+| **Delete records** | Results → **Delete** with 1–100 rows selected | Deletes the selected records. 1–3 records are deleted one request each; 4–100 are deleted in a batch, with progress. Needs the entity's Delete privilege. |
+| **Bulk Delete** | Results → **Delete** with more than 100 rows selected, or with **no rows selected**, or **Bulk Delete** | Submits an asynchronous Bulk Delete job (`BulkDelete`). It runs on the server, and you can track it under Settings → Data Management → Bulk Record Deletion. With no rows selected, the job deletes **every record the query matches**, not just the rows loaded in the grid. Needs the Bulk Delete privilege (`prvBulkDelete`). |
+| **Activate / Deactivate** | Results → **Activate** or **Deactivate** with rows selected | Sets each selected record's Status and Status Reason with an update (`PATCH {EntitySetName}(id)` with `statecode` and `statuscode`), in batches with progress. The options come from the entity's metadata: entities with two states and one status reason each (such as account and contact) go to the state's default status reason; others let you pick the status reason, grouped by state, limited to the allowed transitions when the entity enforces status reason transitions. Off for entities whose states change through their own actions (opportunity, case, quote, order, invoice, contract) and for entities with no Status column. Needs the entity's Write privilege. |
+| **Run workflow** | Results → **Run Workflow** on selected rows | Starts the chosen on-demand workflow (`ExecuteWorkflow`) once per selected record. What the workflow does is up to the workflow. |
+| **Save view (personal)** | **Save As** / **Save**, Personal view | Creates or updates a `userquery` record (your personal view). |
+| **Save view (system)** | **Save As** / **Save**, System view | Checks the query with `ValidateSavedQuery`, then creates or updates a `savedquery` record and publishes it (`PublishXml`). Optionally adds it to the unmanaged solution you choose (`AddSolutionComponent`). Overwriting a view that isn't customizable is blocked. |
+
+Nothing else writes to Dataverse:
+- **Export (Server)** asks Dataverse to build an Excel file (`ExportToExcel`) and changes no data.
+- **Export (Local)** writes an `.xlsx` file to the location you choose.
+- **Display settings** (logical names, value format, entity source, Advanced Find only) are stored by Power Platform ToolBox on your machine, not in Dataverse.
+
 ## 🖼️ Interface Overview
 
 ```
@@ -152,7 +179,7 @@ A powerful, modern FetchXML query builder and data explorer for [Power Platform
 ## 🚀 Getting Started
 
 ### Prerequisites
-- [Power Platform ToolBox](https://github.com/PowerPlatformToolBox/desktop-app) desktop application
+- [Power Platform ToolBox](https://github.com/PowerPlatformToolBox/desktop-app) desktop application, **version 1.2.7 or later**. FetchXML Studio 1.5 targets PPTB 1.2.7 (`minAPI` 1.2.7); 1.4.x works with 1.2.2 or later
 - Connection to a Dataverse environment
 
 ### Installation
@@ -172,6 +199,9 @@ npm ci
 
 # Start development server
 npm run dev
+
+# Run the real UI in a browser against a live Dataverse org (needs `az login`; see dev/README.md)
+npm run dev:harness
 ```
 
 ### Building
@@ -187,7 +217,7 @@ npm run preview
 npm run validate
 ```
 
-**Releases.** CI (`.github/workflows/ci.yml`) runs typecheck, lint, tests, PPTB validation, the build and a package-contents check on every pull request. Pushing a `vX.Y.Z` tag on `main` publishes to npm with provenance and creates the GitHub Release; see [RELEASING.md](RELEASING.md).
+**Releases.** CI (`.github/workflows/ci.yml`) runs typecheck, lint, tests, PPTB validation, the build and a package-contents check on every pull request. `main` holds the current stable release and `dev` the next one. A `vX.Y.Z` tag on `main` publishes to npm `latest`, and a `vX.Y.Z-beta.N` tag on `dev` publishes to npm `beta` as a GitHub pre-release, both with provenance; see [RELEASING.md](RELEASING.md).
 
 **Tool icon.** `package.json` points `icon` at `icons/icon.svg` under `dist/`, where Power Platform ToolBox looks for it. The build bundles `icons/icon-insider.svg` (gold stamp) for prerelease versions such as `1.4.2-beta.7`, and `icons/icon.svg` for releases.