@object-ui/data-objectstack 6.2.2 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,145 @@
 # @object-ui/data-objectstack
 
+## 7.0.0
+
+### Minor Changes
+
+- 30ee761: feat(studio): surface pending drafts on the package detail (ADR-0033)
+
+  After an AI builds an app, its objects/views land as drafts bound to the app package — but Studio's active-only browsers hid them, so the package looked empty and there was no obvious way to find what to review/publish.
+
+  - `MetadataClient.listDrafts({ packageId?, type? })` calls the new `GET /api/v1/meta/_drafts` endpoint, returning pending draft headers (with `packageId`).
+  - The package detail sheet (PackagesPage) now shows a **Pending changes** section listing each drafted item, each linking to the existing per-item review/diff (`?review=1`) so the user can publish it. A just-built app package is no longer shown as empty.
+
+- 053c948: feat: ADR-0047 — interface pages, visualization switcher, and Airtable-parity filters
+
+  End-user interface/list pages reach full rendering and authoring parity:
+
+  - **Spec tabs + visualization switcher** — `ObjectView` now forwards
+    `viewDef.tabs` (stored/served but never rendered) and `viewDef.appearance`
+    (`allowedVisualizations` whitelist), turning on the dormant `ViewSwitcher` when
+    more than one type is whitelisted; effective options = author whitelist ∩
+    capability-resolvable types (kanban needs `groupBy`, calendar a date field, …).
+    `ListView` accepts the canonical `ViewFilterRule[]` tab-filter shape.
+  - **User filters** — render only when `userFilters` is explicitly configured;
+    selections (dropdown values + active tab) mirror into `uf_*` URL params and
+    restore on load, so filtered lists survive reload and are shareable.
+  - **Toolbar polish** — the visualization switcher becomes a compact right-side
+    "Grid ▾" dropdown inside the tool cluster (no extra row); filter tabs and
+    dropdown filters are mutually exclusive.
+  - **Studio authoring** — a usable, schema-driven interface-page inspector
+    (collapsible sections honoured, array-of-enum → multi-select, a None/Tabs/
+    Dropdown `filter-mode` selector where None maps to ABSENCE of `userFilters`),
+    and the Design/Preview tabs render the live list via `InterfaceListPage`
+    (including a non-empty grid when the source view is hollow).
+
+- 5332639: feat(app-shell): render full object forms (incl. master-detail) in screen-flow wizard steps
+
+  `FlowRunner` now renders an `object-form` screen step: when the paused screen
+  carries `kind: 'object-form'`, it mounts the real `<ObjectForm>` for the named
+  object (auto-routing to `MasterDetailForm` for inline child collections),
+  prefilled from the step's `defaults`. The form persists itself (atomic
+  master-detail batch), then resumes the run with the saved record id bound to the
+  step's `idVariable`. `dataSource`/`objects` are threaded through all three
+  `FlowRunner` mount points.
+
+  Also fixes three pre-existing bugs this surfaced (each affects normal forms too):
+
+  - **plugin-form**: `ObjectForm` now forwards `initialValues`/`initialData` when
+    routing to `MasterDetailForm`, so prefilled header values are no longer
+    dropped on master-detail create forms.
+  - **fields**: `PercentField` treated values as `0–1` fractions (`value × 100`),
+    so a `0–100` field (e.g. `probability` default `50`) rendered as `5000%` —
+    exceeding `max=100`, which makes HTML5 constraint validation mark the field
+    `:invalid` and silently block the whole form's submit. It now treats a field
+    declaring `max > 1` as the `0–100` whole-number convention, matching the
+    read-side formatter.
+  - **data-objectstack**: `ObjectStackAdapter.batchTransaction` now sends
+    `credentials: 'include'`, so master-detail batch saves authenticate under the
+    console's cookie session (previously every batch save 401'd).
+
+- d16566f: Atomic master-detail create via the cross-object transactional batch endpoint (ObjectStack #1604).
+
+  When the server exposes the transactional batch endpoint, a NEW parent record and its child line items are now persisted in ONE server transaction — commit all or roll back all — instead of the previous client-orchestrated "create parent → create children → best-effort cleanup on failure" sequence.
+
+  **`@object-ui/data-objectstack` — `ObjectStackAdapter.batchTransaction(operations)`**
+
+  - New method posting `{ operations }` to `POST /api/v1/batch`. Operations run in one server transaction. A field value of `{ $ref: <earlier op index> }` resolves to that op's generated id, so a child can reference its parent created earlier in the same batch (master-detail FK). Throws `ObjectStackError('BATCH_ERROR')` on a non-2xx response.
+
+  **`@object-ui/plugin-form`**
+
+  - `MasterDetailForm` now detects `dataSource.batchTransaction` and, on a NEW parent, builds one atomic batch (parent at index 0, each child FK set to `{ $ref: 0 }`) via the new pure helper `buildMasterDetailBatch`. Client-side total rollups are merged into the parent payload before the batch. Edit mode and adapters without `batchTransaction` keep the existing client-orchestrated path.
+  - `ObjectForm` gained a `submitHandler` hook: when supplied, the form validates and hands the collected values to the host instead of calling `dataSource.create` / `dataSource.update`. `MasterDetailForm` uses it to own the atomic parent+children write while the parent fields are still rendered by `ObjectForm`.
+
+  **`@object-ui/types`**
+
+  - `ObjectFormSchema.submitHandler?: (values) => any | Promise<any>` — typed override for host-owned persistence.
+
+  Pairs with the framework-side ambient-transaction fix (ObjectQL `AsyncLocalStorage` transaction propagation) and the `/api/v1/batch` endpoint added in `@objectstack/rest`.
+
+### Patch Changes
+
+- b99d9bd: ADR-0048: package-scope the Studio metadata editor read. Two installed packages
+  may ship metadata with the same `type`/`name`; the editor now resolves the right
+  one instead of first-match.
+
+  - `MetadataClient`: `layered()` and `getDraft()` accept `{ packageId }`, and
+    `get()` emits the `package` query param (→ server prefer-local, `?package=`).
+  - `ResourceListPage`: each item's edit link carries its owning package
+    (`?package=<row._packageId>`), so even the unscoped "all" list disambiguates;
+    falls back to the workspace suffix for runtime/overlay-only rows.
+  - `ResourceEditPage`: reads `?package=` and scopes the layered + draft read to
+    that package. (The route's `:appName` is the Studio app, not the edited item's
+    owner, so the scope must come from the URL, not the active app.)
+
+- a58c6b8: fix(datasource): exclude form-family views from `listViews()`
+
+  `OBJECTSTACKDataSource.listViews(objectName)` feeds the object list-view
+  switcher (`ObjectView` → `ViewTabBar`), but returned **every** view bound to
+  the object — including form-family ones. With the backend now exposing each
+  view as an independent **ViewItem** carrying a `viewKind` discriminant
+  (ADR-0017, "Object has-many View"), a form view such as `crm_activity.default`
+  (expanded from `formViews.default`) leaked in as a spurious switcher tab and,
+  when opened, fell back to the default grid.
+
+  `listViews()` now filters out `viewKind` `form`/`detail` items so only
+  list-family views reach the switcher. Bare view specs without a `viewKind`
+  (legacy artifacts and user-saved views) are still treated as list views.
+
+- Updated dependencies [5976ba3]
+- Updated dependencies [eaccefd]
+- Updated dependencies [f7f325d]
+- Updated dependencies [c12986e]
+- Updated dependencies [71d7ce0]
+- Updated dependencies [053c948]
+- Updated dependencies [ddbe4a2]
+- Updated dependencies [2d47e94]
+- Updated dependencies [9049bbe]
+- Updated dependencies [cb2fdb1]
+- Updated dependencies [c3749eb]
+- Updated dependencies [6cfa330]
+- Updated dependencies [ad8ade6]
+- Updated dependencies [d54346c]
+- Updated dependencies [3870c20]
+- Updated dependencies [b88c560]
+- Updated dependencies [d16566f]
+- Updated dependencies [1394e34]
+- Updated dependencies [300d755]
+- Updated dependencies [4eb9cb6]
+- Updated dependencies [7c239fd]
+- Updated dependencies [858ad94]
+- Updated dependencies [2270239]
+- Updated dependencies [8d1195d]
+  - @object-ui/core@7.0.0
+  - @object-ui/types@7.0.0
+
+## 6.2.3
+
+### Patch Changes
+
+- @object-ui/types@6.2.3
+- @object-ui/core@6.2.3
+
 ## 6.2.2
 
 ### Patch Changes

package/dist/index.cjs

@@ -814,9 +814,12 @@ var MetadataClient = class _MetadataClient {
     __publicField(this, "base");
     __publicField(this, "fetchImpl");
     __publicField(this, "headers");
+    /** ADR-0037: when true, reads render the draft-overlaid world. */
+    __publicField(this, "previewDrafts");
     this.base = buildBase(config);
     this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
     this.headers = { Accept: "application/json", ...config.headers ?? {} };
+    this.previewDrafts = config.previewDrafts === true;
   }
   /** Update the client's environment scope at runtime. */
   withEnvironment(environmentId) {
@@ -824,7 +827,24 @@ var MetadataClient = class _MetadataClient {
       baseUrl: this.base.replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, "").replace(/\/+$/, ""),
       environmentId,
       fetch: this.fetchImpl,
-      headers: this.headers
+      headers: this.headers,
+      previewDrafts: this.previewDrafts
+    });
+  }
+  /**
+   * Derive a client whose reads render the draft-overlaid world (or not).
+   * Same base/fetch/headers; used by the app-shell to switch the whole
+   * renderer tree into ADR-0037 preview mode off one URL flag.
+   */
+  withPreviewDrafts(previewDrafts) {
+    if (previewDrafts === this.previewDrafts) return this;
+    const envMatch = this.base.match(/\/api\/v\d+\/environments\/([^/]+)\/meta$/);
+    return new _MetadataClient({
+      baseUrl: this.base.replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, "").replace(/\/+$/, ""),
+      ...envMatch ? { environmentId: decodeURIComponent(envMatch[1]) } : {},
+      fetch: this.fetchImpl,
+      headers: this.headers,
+      previewDrafts
     });
   }
   /** List all registered metadata types (returns the registry rows). */
@@ -842,7 +862,10 @@ var MetadataClient = class _MetadataClient {
   }
   /** List items of a metadata type (e.g. `object`, `field`, `view`). */
   async list(type, options = {}) {
-    const qs = options.packageId ? `?package=${encodeURIComponent(options.packageId)}` : "";
+    const params = [];
+    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
+    if (this.previewDrafts) params.push("preview=draft");
+    const qs = params.length ? `?${params.join("&")}` : "";
     const url = `${this.base}/${encodeURIComponent(type)}${qs}`;
     const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
     if (!res.ok) throw await parseError(res);
@@ -853,25 +876,70 @@ var MetadataClient = class _MetadataClient {
     }
     return [];
   }
+  /**
+   * List pending DRAFT items (ADR-0033) — what an AI authored but nobody
+   * published yet. `list()` only sees published/active metadata, so a
+   * just-built app package looks empty there; this surfaces the drafts so the
+   * console can show a "pending changes" view and draft-aware package contents.
+   * Optionally narrow by `packageId` and/or `type`. Returns light headers
+   * (no body) carrying `packageId` for grouping.
+   */
+  async listDrafts(options = {}) {
+    const params = [];
+    if (options.packageId) params.push(`packageId=${encodeURIComponent(options.packageId)}`);
+    if (options.type) params.push(`type=${encodeURIComponent(options.type)}`);
+    const qs = params.length ? `?${params.join("&")}` : "";
+    const url = `${this.base}/_drafts${qs}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (!res.ok) throw await parseError(res);
+    const data = await res.json();
+    if (Array.isArray(data)) return data;
+    return data?.drafts ?? data?.data?.drafts ?? [];
+  }
   /**
    * Get a single metadata item. Returns the unwrapped item content
    * (matching the framework REST handler which calls `res.json(item)`).
    * Returns `null` on 404 to keep the call-site ergonomic.
    */
-  async get(type, name) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`;
+  async get(type, name, options = {}) {
+    const params = [];
+    if (options.state === "draft") params.push("state=draft");
+    else if (this.previewDrafts) params.push("preview=draft");
+    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
+    const qs = params.length ? `?${params.join("&")}` : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
     const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
     if (res.status === 404) return null;
     if (!res.ok) throw await parseError(res);
     return await res.json();
   }
+  /**
+   * Read the pending draft body for an item (`?state=draft`). Returns
+   * `null` when there is no draft pending. Draft reads do NOT fall
+   * back to the published overlay or the artifact registry — a `null`
+   * unambiguously means "nothing to publish".
+   *
+   * Note: the framework wraps draft responses in an envelope
+   * `{ type, name, item }` (matching `getMetaItem`); callers should
+   * read `.item` to get the body. The legacy `get()` returns the
+   * unwrapped body, so this method preserves that asymmetry by
+   * returning whatever the server sent.
+   */
+  async getDraft(type, name, options = {}) {
+    return this.get(type, name, { state: "draft", ...options.packageId ? { packageId: options.packageId } : {} });
+  }
   /**
    * Save (PUT) a metadata item. The framework accepts both the bare
    * item payload and the `{ item: ... }` / `{ metadata: ... }`
-   * envelopes; we send bare for consistency.
+   * envelopes; we send bare for consistency. Pass `mode: 'draft'` to
+   * stage the change without publishing (Studio's "Save" button).
    */
   async save(type, name, item, options = {}) {
-    const qs = options.force ? "?force=true" : "";
+    const params = [];
+    if (options.force) params.push("force=true");
+    if (options.mode === "draft") params.push("mode=draft");
+    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
+    const qs = params.length ? `?${params.join("&")}` : "";
     const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
     const headers = {
       ...this.headers,
@@ -887,13 +955,38 @@ var MetadataClient = class _MetadataClient {
     if (!res.ok) throw await parseError(res);
     return await res.json();
   }
+  /**
+   * Publish a single pending draft BY REFERENCE — promotes the draft row for
+   * `(type, name)` into the active overlay and drops the draft. Works for ANY
+   * draft, including ones with no `packageId` binding (which the package-scoped
+   * `/packages/:id/publish-drafts` flow cannot reach). Use this to publish the
+   * exact set returned by {@link listDrafts} without needing a package.
+   *
+   * Returns the server result. For `seed` drafts the protocol also materializes
+   * the rows and reports under `seedApplied` — a data problem never fails the
+   * publish, so callers should check `seedApplied?.success` and warn the user
+   * rather than assume the data went live.
+   */
+  async publishDraft(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      headers: { ...this.headers, "Content-Type": "application/json", Accept: "application/json" },
+      body: "{}"
+    });
+    if (!res.ok) throw await parseError(res);
+    const body = await res.json().catch(() => ({}));
+    const inner = body?.data && typeof body.data === "object" ? body.data : body;
+    return inner;
+  }
   /**
    * Get the 3-state layered view of a metadata item (Phase 3a). Returns
    * `code` (the artifact / fallback default), `overlay` (the saved
    * customisation, if any), and `effective` (what the runtime sees).
    */
-  async layered(type, name) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true`;
+  async layered(type, name, options = {}) {
+    const pkg = options.packageId ? `&package=${encodeURIComponent(options.packageId)}` : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true${pkg}`;
     const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
     if (res.status === 404) {
       return { code: null, overlay: null, overlayScope: null, effective: null };
@@ -913,7 +1006,50 @@ var MetadataClient = class _MetadataClient {
       code: body.code ?? null,
       overlay: body.overlay ?? null,
       overlayScope: body.overlayScope ?? null,
-      effective: body.effective ?? null
+      effective: body.effective ?? null,
+      ...body._diagnostics ? { _diagnostics: body._diagnostics } : {},
+      // ADR-0010 Phase 4 — pass through the metadata-protection envelope so
+      // the editor can render lock affordances without a second round trip.
+      ...body.lock !== void 0 ? { lock: body.lock } : {},
+      ...body.lockReason !== void 0 ? { lockReason: body.lockReason } : {},
+      ...body.lockSource !== void 0 ? { lockSource: body.lockSource } : {},
+      ...body.lockDocsUrl !== void 0 ? { lockDocsUrl: body.lockDocsUrl } : {},
+      ...body.provenance !== void 0 ? { provenance: body.provenance } : {},
+      ...body.packageId !== void 0 ? { packageId: body.packageId } : {},
+      ...body.packageVersion !== void 0 ? { packageVersion: body.packageVersion } : {},
+      ...body.editable !== void 0 ? { editable: body.editable } : {},
+      ...body.deletable !== void 0 ? { deletable: body.deletable } : {},
+      ...body.resettable !== void 0 ? { resettable: body.resettable } : {}
+    };
+  }
+  /**
+   * Cross-type sweep of load-time validation results — calls
+   * `GET /meta/diagnostics`. Returns every entry the framework
+   * considers invalid (or, when `severity: 'warning'`, also entries
+   * with only warnings).
+   *
+   * Used by the Studio's governance overview page and by the
+   * directory page to show "N invalid" badges per metadata type.
+   */
+  async diagnostics(options = {}) {
+    const params = [];
+    if (options.type) params.push(`type=${encodeURIComponent(options.type)}`);
+    if (options.severity) params.push(`severity=${encodeURIComponent(options.severity)}`);
+    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
+    const qs = params.length ? `?${params.join("&")}` : "";
+    const url = `${this.base}/diagnostics${qs}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (res.status === 404) {
+      return { entries: [], total: 0, scannedTypes: 0, scannedItems: 0, stats: {} };
+    }
+    if (!res.ok) throw await parseError(res);
+    const data = await res.json();
+    return {
+      entries: Array.isArray(data.entries) ? data.entries : [],
+      total: typeof data.total === "number" ? data.total : 0,
+      scannedTypes: typeof data.scannedTypes === "number" ? data.scannedTypes : 0,
+      scannedItems: typeof data.scannedItems === "number" ? data.scannedItems : 0,
+      stats: data.stats && typeof data.stats === "object" ? data.stats : {}
     };
   }
   /**
@@ -932,9 +1068,12 @@ var MetadataClient = class _MetadataClient {
   /**
    * Reset a metadata customization overlay back to the artifact default.
    * Idempotent: returns the result even when no overlay row existed.
+   * Pass `state: 'draft'` to discard the pending draft only (keeps the
+   * published overlay intact) — useful for a Studio "Discard draft" button.
    */
   async reset(type, name, options = {}) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`;
+    const qs = options.state === "draft" ? "?state=draft" : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
     const headers = { ...this.headers };
     if (options.ifMatch) headers["If-Match"] = options.ifMatch;
     if (options.actor) headers["X-Actor"] = options.actor;
@@ -942,6 +1081,75 @@ var MetadataClient = class _MetadataClient {
     if (!res.ok) throw await parseError(res);
     return await res.json();
   }
+  /**
+   * Promote the pending draft of an item to the active overlay
+   * (POST `/meta/:type/:name/publish`). Returns
+   * `{ success, version, seq, message }`. Throws a `404 no_draft` if
+   * nothing is pending and `409 metadata_conflict` if the published
+   * overlay moved while the draft was sitting.
+   */
+  async publish(type, name, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
+    const headers = {
+      ...this.headers,
+      "Content-Type": "application/json"
+    };
+    if (options.actor) headers["X-Actor"] = options.actor;
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(options.message ? { message: options.message } : {})
+    });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
+  /**
+   * Restore an item to a previous version (POST `/meta/:type/:name/rollback`).
+   * The server reads the history row at `toVersion`, writes its body back
+   * as the active overlay with `operation_type='revert'`. Returns
+   * `{ success, version, seq, restoredFromVersion, message }`. Throws
+   * `404 version_not_found` for unknown versions and `409 version_not_restorable`
+   * when the target version is a delete tombstone.
+   */
+  async rollback(type, name, toVersion, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/rollback`;
+    const headers = {
+      ...this.headers,
+      "Content-Type": "application/json"
+    };
+    if (options.actor) headers["X-Actor"] = options.actor;
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        toVersion,
+        ...options.message ? { message: options.message } : {}
+      })
+    });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
+  /**
+   * Compute a structured top-level key diff between two history versions
+   * (GET `/meta/:type/:name/diff?from=&to=`). Returns
+   * `{ added, removed, changed }` where each entry carries a `path` and
+   * the relevant value(s). Useful for "what changed in this draft?" and
+   * pre-rollback previews.
+   */
+  async diff(type, name, fromVersion, toVersion) {
+    const params = new URLSearchParams();
+    if (fromVersion !== void 0) params.set("from", String(fromVersion));
+    if (toVersion !== void 0) params.set("to", String(toVersion));
+    const qs = params.toString();
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/diff${qs ? `?${qs}` : ""}`;
+    const res = await this.fetchImpl(url, {
+      method: "GET",
+      headers: this.headers,
+      cache: "no-store"
+    });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
   /** Fetch the durable history (change log) for one metadata item. */
   async history(type, name, options = {}) {
     const params = new URLSearchParams();
@@ -953,6 +1161,22 @@ var MetadataClient = class _MetadataClient {
     if (!res.ok) throw await parseError(res);
     return await res.json();
   }
+  /**
+   * Fetch the protection-audit trail for one metadata item
+   * (ADR-0010 §3.6 / Phase 4.1). Shows every save/publish/rollback/
+   * delete/reset attempt — allowed, denied, or forced — so the
+   * Studio "审计日志 / Audit log" tab can render who tried what
+   * and whether a lock blocked it.
+   */
+  async audit(type, name, options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const qs = params.toString();
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/audit${qs ? `?${qs}` : ""}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
 };
 
 // src/security.ts
@@ -1437,7 +1661,7 @@ var ObjectStackAdapter = class {
     if (existing) return existing;
     const promise = (async () => {
       await this.connect();
-      if (params?.$expand && params.$expand.length > 0) {
+      if (params?.$expand && params.$expand.length > 0 || params?.$search != null && String(params.$search).trim() !== "") {
         const result = await this.rawFindWithPopulate(resource, params);
         return this.normalizeQueryResult(result, params);
       }
@@ -1635,6 +1859,34 @@ var ObjectStackAdapter = class {
    * @param data - Array of records to process
    * @returns Promise resolving to array of results
    */
+  /**
+   * Cross-object transactional batch (ObjectStack #1604). Runs the operations
+   * in ONE server transaction — commit all or roll back all. A field value of
+   * `{ $ref: <earlier op index> }` resolves to that op's created id, so a child
+   * can reference its parent created earlier in the same batch (master-detail).
+   */
+  async batchTransaction(operations) {
+    const url = `${this.baseUrl}/api/v1/batch`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...this.getAuthHeaders() },
+      // Send the session cookie too: in the browser console auth is cookie-based
+      // (no bearer `token`), so without `credentials: 'include'` this raw fetch
+      // is unauthenticated — every master-detail batch save would 401. Bearer
+      // (server-to-server) and cookie (console) auth now both work.
+      credentials: "include",
+      body: JSON.stringify({ operations })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ message: response.statusText }));
+      throw new ObjectStackError(
+        error.error || error.message || `Batch failed with status ${response.status}`,
+        "BATCH_ERROR",
+        response.status
+      );
+    }
+    return response.json();
+  }
   async bulk(resource, operation, data) {
     await this.connect();
     if (!data || data.length === 0) {
@@ -1772,13 +2024,14 @@ var ObjectStackAdapter = class {
     const resultObj = result;
     const records = resultObj.records || resultObj.value || [];
     const total = resultObj.total ?? resultObj.count ?? records.length;
+    const hasMore = typeof resultObj.hasMore === "boolean" ? resultObj.hasMore : params?.$top ? records.length === params.$top : false;
     return {
       data: records,
       total,
       // Calculate page number safely
       page: params?.$skip && params.$top ? Math.floor(params.$skip / params.$top) + 1 : 1,
       pageSize: params?.$top,
-      hasMore: params?.$top ? records.length === params.$top : false
+      hasMore
     };
   }
   /**
@@ -1798,6 +2051,12 @@ var ObjectStackAdapter = class {
     if (params.$skip !== void 0) {
       queryParams.set("skip", String(params.$skip));
     }
+    if (params.$search != null && String(params.$search).trim() !== "") {
+      queryParams.set("search", String(params.$search).trim());
+    }
+    if (params.$searchFields && params.$searchFields.length > 0) {
+      queryParams.set("searchFields", params.$searchFields.join(","));
+    }
     if (params.$select && params.$select.length > 0) {
       const selectFields = params.$select.includes("id") ? params.$select : ["id", ...params.$select];
       queryParams.set("select", selectFields.join(","));
@@ -1898,6 +2157,12 @@ var ObjectStackAdapter = class {
     if (params.$top !== void 0) {
       options.top = params.$top;
     }
+    if (params.$search != null && String(params.$search).trim() !== "") {
+      options.search = String(params.$search).trim();
+    }
+    if (params.$searchFields && params.$searchFields.length > 0) {
+      options.searchFields = params.$searchFields;
+    }
     return options;
   }
   /**
@@ -2004,7 +2269,7 @@ var ObjectStackAdapter = class {
     try {
       const cacheKey = `view:${objectName}:${viewId}`;
       return await this.metadataCache.get(cacheKey, async () => {
-        const result = await this.client.meta.getItem(objectName, viewId);
+        const result = await this.client.meta.getItem("view", viewId);
         if (result && result.item) return result.item;
         return result ?? null;
       });
@@ -2063,12 +2328,26 @@ var ObjectStackAdapter = class {
     try {
       const result = await this.client.meta.getItems("view");
       const items = Array.isArray(result?.items) ? result.items : Array.isArray(result) ? result : [];
+      const FORM_FAMILY = /* @__PURE__ */ new Set(["form", "detail"]);
       return items.filter((v) => {
         if (!v) return false;
         const spec = v.list ?? v;
         const obj = spec?.data?.object ?? spec?.object ?? spec?.objectName;
-        return obj === objectName;
-      }).map((v) => v.list ?? v);
+        if (obj !== objectName) return false;
+        const viewKind = v.viewKind ?? spec?.viewKind;
+        return !(viewKind && FORM_FAMILY.has(viewKind));
+      }).map((v) => {
+        const spec = v.list ?? v;
+        if (spec && spec.config && typeof spec.config === "object") {
+          return {
+            ...spec.config,
+            name: spec.name ?? spec.config.name,
+            label: spec.label ?? spec.config.label,
+            isDefault: !!spec.isDefault
+          };
+        }
+        return spec;
+      });
     } catch (err) {
       console.warn("[OBJECTSTACKDataSource] listViews failed:", err);
       return [];
@@ -2285,6 +2564,56 @@ var ObjectStackAdapter = class {
       return this.aggregateClientSide(records, params);
     }
   }
+  /**
+   * Run a semantic-layer `dataset` (ADR-0021) and return chart-ready rows.
+   *
+   * Posts to `POST /api/v1/analytics/dataset/query` (see `@objectstack/rest`
+   * `registerAnalyticsEndpoints`). Accepts either a saved dataset name or an
+   * inline draft definition — the inline form is what the Studio dataset
+   * editor sends to preview an unsaved draft. The adapter's bearer token is
+   * forwarded so tenant/RLS scoping (ADR-0021 D-C) is enforced server-side.
+   *
+   * Unlike {@link aggregate}, this does NOT fall back to client-side
+   * aggregation: cross-object joins can only run on the server, so a failure
+   * is surfaced to the caller (the preview panel shows the error) rather than
+   * silently returning wrong numbers.
+   *
+   * @param dataset - An inline dataset definition (draft) OR a saved dataset name.
+   * @param selection - Dimension/measure names to project + runtime directives.
+   */
+  async queryDataset(dataset, selection) {
+    await this.connect();
+    const base = (this.baseUrl || "").replace(/\/$/, "");
+    const url = `${base}/api/v1/analytics/dataset/query`;
+    const previewDrafts = typeof window !== "undefined" && new URLSearchParams(window.location.search).get("preview") === "draft";
+    const requestBody = typeof dataset === "string" ? { datasetName: dataset, selection, ...previewDrafts ? { previewDrafts: true } : {} } : { dataset, selection, ...previewDrafts ? { previewDrafts: true } : {} };
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.token ? { Authorization: `Bearer ${this.token}` } : {}
+      },
+      body: JSON.stringify(requestBody)
+    });
+    if (!res.ok) {
+      let detail = "";
+      try {
+        const errBody = await res.json();
+        detail = errBody?.message || errBody?.error || JSON.stringify(errBody);
+      } catch {
+      }
+      throw new Error(`Dataset query failed: ${res.status} ${res.statusText}${detail ? ` \u2014 ${detail}` : ""}`);
+    }
+    const payload = await res.json();
+    const data = payload && typeof payload === "object" && "success" in payload && "data" in payload ? payload.data : payload;
+    const rows = Array.isArray(data?.rows) ? data.rows : Array.isArray(data) ? data : [];
+    const fields = Array.isArray(data?.fields) ? data.fields : [];
+    const object = typeof data?.object === "string" ? data.object : void 0;
+    const dimensionFields = data?.dimensionFields && typeof data.dimensionFields === "object" ? data.dimensionFields : void 0;
+    const drillRawRows = Array.isArray(data?.drillRawRows) ? data.drillRawRows : void 0;
+    const totals = Array.isArray(data?.totals) ? data.totals : void 0;
+    return { rows, fields, object, dimensionFields, drillRawRows, totals };
+  }
   /** Client-side aggregation fallback */
   aggregateClientSide(records, params) {
     const { field, function: aggFn, groupBy } = params;