@object-ui/data-objectstack 4.0.9 → 4.0.11

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @object-ui/data-objectstack
 
+## 4.0.11
+
+### Patch Changes
+
+- @object-ui/types@4.0.11
+- @object-ui/core@4.0.11
+
+## 4.0.10
+
+### Patch Changes
+
+- @object-ui/types@4.0.10
+- @object-ui/core@4.0.10
+
 ## 4.0.9
 
 ### Patch Changes

package/dist/index.cjs

@@ -962,6 +962,11 @@ var ObjectStackAdapter = class {
     // multiple sibling components requesting the same dataset on first paint)
     // into a single network round trip.
     __publicField(this, "inflightFinds", /* @__PURE__ */ new Map());
+    // Resources that have responded 404 at least once (collection not installed
+    // on this backend). Subsequent find() calls short-circuit to an empty result
+    // so optional collections like sys_presence don't hammer the server with
+    // failing requests on every record open / panel render.
+    __publicField(this, "missingResources", /* @__PURE__ */ new Set());
     this.client = new import_client.ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
@@ -1099,18 +1104,29 @@ var ObjectStackAdapter = class {
    * Converts OData-style params to ObjectStack query options.
    */
   async find(resource, params) {
+    if (this.missingResources.has(resource)) {
+      return { data: [], total: 0 };
+    }
     const key = `${resource}::${stableStringify(params)}`;
     const existing = this.inflightFinds.get(key);
     if (existing) return existing;
     const promise = (async () => {
       await this.connect();
       if (params?.$expand && params.$expand.length > 0) {
-        const result2 = await this.rawFindWithPopulate(resource, params);
-        return this.normalizeQueryResult(result2, params);
+        const result = await this.rawFindWithPopulate(resource, params);
+        return this.normalizeQueryResult(result, params);
       }
       const queryOptions = this.convertQueryParams(params);
-      const result = await this.client.data.find(resource, queryOptions);
-      return this.normalizeQueryResult(result, params);
+      try {
+        const result = await this.client.data.find(resource, queryOptions);
+        return this.normalizeQueryResult(result, params);
+      } catch (err) {
+        if (is404Error(err)) {
+          this.missingResources.add(resource);
+          return { data: [], total: 0 };
+        }
+        throw err;
+      }
     })();
     this.inflightFinds.set(key, promise);
     const cleanup = () => {
@@ -1586,20 +1602,129 @@ var ObjectStackAdapter = class {
   async updateViewConfig(objectName, viewId, config) {
     await this.connect();
     try {
+      const merged = { ...config || {}, object: config?.object || objectName, name: viewId };
       const result = await this.client.meta.saveItem(
-        objectName,
+        "view",
         viewId,
-        config
+        merged
       );
       const cacheKey = `view:${objectName}:${viewId}`;
       this.metadataCache.invalidate?.(cacheKey);
       this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
+      this.metadataCache.invalidate?.(`views:${objectName}`);
       if (result && result.item) return result.item;
       return result ?? void 0;
     } catch (err) {
       throw err;
     }
   }
+  /**
+   * List user-created views for a given object via the metadata overlay
+   * API (ADR-0005). Replaces the legacy `find('sys_view', {...})` path
+   * that wrote to a physical `sys_view` table whose columns no longer
+   * match the view spec shape.
+   *
+   * Returns view spec objects with their canonical `name` as identifier.
+   * Filters by `data.object === objectName` (or top-level `object`)
+   * client-side because the metadata index is name-only, not field-typed.
+   */
+  async listViews(objectName) {
+    await this.connect();
+    try {
+      const result = await this.client.meta.getItems("view");
+      const items = Array.isArray(result?.items) ? result.items : Array.isArray(result) ? result : [];
+      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);
+    } catch (err) {
+      console.warn("[OBJECTSTACKDataSource] listViews failed:", err);
+      return [];
+    }
+  }
+  /**
+   * Create a new overlay view for an object. The view's `name` is the
+   * stable identifier — must be unique within the project scope. Returns
+   * the persisted view spec (or undefined when the server doesn't echo).
+   *
+   * Generates a snake_case name if `spec.name` is not provided by appending
+   * a short timestamp suffix to the source-name hint.
+   */
+  async createView(objectName, spec) {
+    await this.connect();
+    let name = String(spec?.name || "").trim();
+    if (!name) {
+      let base = String(spec?.label || objectName || "view").toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 40);
+      if (!base || /^[0-9]/.test(base)) {
+        base = base ? `view_${base}` : "view";
+      }
+      const suffix = Date.now().toString(36);
+      name = `${base}_${suffix}`;
+    }
+    const fullSpec = {
+      ...spec,
+      name,
+      object: spec?.object || objectName,
+      data: spec?.data || { provider: "object", object: objectName }
+    };
+    try {
+      const result = await this.client.meta.saveItem("view", name, fullSpec);
+      this.metadataCache.invalidate?.(`views:${objectName}`);
+      if (result && result.item) return result.item;
+      return fullSpec;
+    } catch (err) {
+      throw err;
+    }
+  }
+  /**
+   * Apply a partial update to an existing overlay view. Reads the current
+   * overlay (or seeds from artifact), merges, and writes back. ADR-0005
+   * overlay rows store the *full* view document, so partial updates require
+   * a read-merge-write cycle.
+   */
+  async updateView(objectName, viewName, partial) {
+    await this.connect();
+    let current = {};
+    try {
+      const r = await this.client.meta.getItem("view", viewName);
+      current = r && (r.item || r) || {};
+      if (current?.list) current = current.list;
+    } catch {
+    }
+    const merged = {
+      ...current,
+      ...partial,
+      name: viewName,
+      object: current?.object || current?.data?.object || objectName
+    };
+    try {
+      const result = await this.client.meta.saveItem("view", viewName, merged);
+      this.metadataCache.invalidate?.(`views:${objectName}`);
+      this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+      if (result && result.item) return result.item;
+      return merged;
+    } catch (err) {
+      throw err;
+    }
+  }
+  /**
+   * Delete an overlay view (reset to artifact default if one exists, or
+   * remove entirely if it was a user-created view). Routes to
+   * `DELETE /api/v1/meta/view/:name`.
+   */
+  async deleteView(objectName, viewName) {
+    await this.connect();
+    try {
+      const result = await this.client.meta.deleteItem("view", viewName);
+      this.metadataCache.invalidate?.(`views:${objectName}`);
+      this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+      return { deleted: !!(result?.deleted ?? result?.reset ?? true) };
+    } catch (err) {
+      throw err;
+    }
+  }
   /**
    * Get an application definition by name or ID.
    * Attempts to fetch from the server metadata API.

package/dist/index.d.cts

@@ -734,6 +734,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private token?;
     private fetchImpl;
     private inflightFinds;
+    private missingResources;
     constructor(config: {
         baseUrl: string;
         token?: string;
@@ -896,6 +897,41 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @param config - Full view definition to persist
      */
     updateViewConfig(objectName: string, viewId: string, config: Record<string, any>): Promise<Record<string, any> | void>;
+    /**
+     * List user-created views for a given object via the metadata overlay
+     * API (ADR-0005). Replaces the legacy `find('sys_view', {...})` path
+     * that wrote to a physical `sys_view` table whose columns no longer
+     * match the view spec shape.
+     *
+     * Returns view spec objects with their canonical `name` as identifier.
+     * Filters by `data.object === objectName` (or top-level `object`)
+     * client-side because the metadata index is name-only, not field-typed.
+     */
+    listViews(objectName: string): Promise<any[]>;
+    /**
+     * Create a new overlay view for an object. The view's `name` is the
+     * stable identifier — must be unique within the project scope. Returns
+     * the persisted view spec (or undefined when the server doesn't echo).
+     *
+     * Generates a snake_case name if `spec.name` is not provided by appending
+     * a short timestamp suffix to the source-name hint.
+     */
+    createView(objectName: string, spec: Record<string, any>): Promise<Record<string, any> | void>;
+    /**
+     * Apply a partial update to an existing overlay view. Reads the current
+     * overlay (or seeds from artifact), merges, and writes back. ADR-0005
+     * overlay rows store the *full* view document, so partial updates require
+     * a read-merge-write cycle.
+     */
+    updateView(objectName: string, viewName: string, partial: Record<string, any>): Promise<Record<string, any> | void>;
+    /**
+     * Delete an overlay view (reset to artifact default if one exists, or
+     * remove entirely if it was a user-created view). Routes to
+     * `DELETE /api/v1/meta/view/:name`.
+     */
+    deleteView(objectName: string, viewName: string): Promise<{
+        deleted: boolean;
+    }>;
     /**
      * Get an application definition by name or ID.
      * Attempts to fetch from the server metadata API.

package/dist/index.d.ts

@@ -734,6 +734,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private token?;
     private fetchImpl;
     private inflightFinds;
+    private missingResources;
     constructor(config: {
         baseUrl: string;
         token?: string;
@@ -896,6 +897,41 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @param config - Full view definition to persist
      */
     updateViewConfig(objectName: string, viewId: string, config: Record<string, any>): Promise<Record<string, any> | void>;
+    /**
+     * List user-created views for a given object via the metadata overlay
+     * API (ADR-0005). Replaces the legacy `find('sys_view', {...})` path
+     * that wrote to a physical `sys_view` table whose columns no longer
+     * match the view spec shape.
+     *
+     * Returns view spec objects with their canonical `name` as identifier.
+     * Filters by `data.object === objectName` (or top-level `object`)
+     * client-side because the metadata index is name-only, not field-typed.
+     */
+    listViews(objectName: string): Promise<any[]>;
+    /**
+     * Create a new overlay view for an object. The view's `name` is the
+     * stable identifier — must be unique within the project scope. Returns
+     * the persisted view spec (or undefined when the server doesn't echo).
+     *
+     * Generates a snake_case name if `spec.name` is not provided by appending
+     * a short timestamp suffix to the source-name hint.
+     */
+    createView(objectName: string, spec: Record<string, any>): Promise<Record<string, any> | void>;
+    /**
+     * Apply a partial update to an existing overlay view. Reads the current
+     * overlay (or seeds from artifact), merges, and writes back. ADR-0005
+     * overlay rows store the *full* view document, so partial updates require
+     * a read-merge-write cycle.
+     */
+    updateView(objectName: string, viewName: string, partial: Record<string, any>): Promise<Record<string, any> | void>;
+    /**
+     * Delete an overlay view (reset to artifact default if one exists, or
+     * remove entirely if it was a user-created view). Routes to
+     * `DELETE /api/v1/meta/view/:name`.
+     */
+    deleteView(objectName: string, viewName: string): Promise<{
+        deleted: boolean;
+    }>;
     /**
      * Get an application definition by name or ID.
      * Attempts to fetch from the server metadata API.

package/dist/index.js

@@ -919,6 +919,11 @@ var ObjectStackAdapter = class {
     // multiple sibling components requesting the same dataset on first paint)
     // into a single network round trip.
     __publicField(this, "inflightFinds", /* @__PURE__ */ new Map());
+    // Resources that have responded 404 at least once (collection not installed
+    // on this backend). Subsequent find() calls short-circuit to an empty result
+    // so optional collections like sys_presence don't hammer the server with
+    // failing requests on every record open / panel render.
+    __publicField(this, "missingResources", /* @__PURE__ */ new Set());
     this.client = new ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
@@ -1056,18 +1061,29 @@ var ObjectStackAdapter = class {
    * Converts OData-style params to ObjectStack query options.
    */
   async find(resource, params) {
+    if (this.missingResources.has(resource)) {
+      return { data: [], total: 0 };
+    }
     const key = `${resource}::${stableStringify(params)}`;
     const existing = this.inflightFinds.get(key);
     if (existing) return existing;
     const promise = (async () => {
       await this.connect();
       if (params?.$expand && params.$expand.length > 0) {
-        const result2 = await this.rawFindWithPopulate(resource, params);
-        return this.normalizeQueryResult(result2, params);
+        const result = await this.rawFindWithPopulate(resource, params);
+        return this.normalizeQueryResult(result, params);
       }
       const queryOptions = this.convertQueryParams(params);
-      const result = await this.client.data.find(resource, queryOptions);
-      return this.normalizeQueryResult(result, params);
+      try {
+        const result = await this.client.data.find(resource, queryOptions);
+        return this.normalizeQueryResult(result, params);
+      } catch (err) {
+        if (is404Error(err)) {
+          this.missingResources.add(resource);
+          return { data: [], total: 0 };
+        }
+        throw err;
+      }
     })();
     this.inflightFinds.set(key, promise);
     const cleanup = () => {
@@ -1543,20 +1559,129 @@ var ObjectStackAdapter = class {
   async updateViewConfig(objectName, viewId, config) {
     await this.connect();
     try {
+      const merged = { ...config || {}, object: config?.object || objectName, name: viewId };
       const result = await this.client.meta.saveItem(
-        objectName,
+        "view",
         viewId,
-        config
+        merged
       );
       const cacheKey = `view:${objectName}:${viewId}`;
       this.metadataCache.invalidate?.(cacheKey);
       this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
+      this.metadataCache.invalidate?.(`views:${objectName}`);
       if (result && result.item) return result.item;
       return result ?? void 0;
     } catch (err) {
       throw err;
     }
   }
+  /**
+   * List user-created views for a given object via the metadata overlay
+   * API (ADR-0005). Replaces the legacy `find('sys_view', {...})` path
+   * that wrote to a physical `sys_view` table whose columns no longer
+   * match the view spec shape.
+   *
+   * Returns view spec objects with their canonical `name` as identifier.
+   * Filters by `data.object === objectName` (or top-level `object`)
+   * client-side because the metadata index is name-only, not field-typed.
+   */
+  async listViews(objectName) {
+    await this.connect();
+    try {
+      const result = await this.client.meta.getItems("view");
+      const items = Array.isArray(result?.items) ? result.items : Array.isArray(result) ? result : [];
+      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);
+    } catch (err) {
+      console.warn("[OBJECTSTACKDataSource] listViews failed:", err);
+      return [];
+    }
+  }
+  /**
+   * Create a new overlay view for an object. The view's `name` is the
+   * stable identifier — must be unique within the project scope. Returns
+   * the persisted view spec (or undefined when the server doesn't echo).
+   *
+   * Generates a snake_case name if `spec.name` is not provided by appending
+   * a short timestamp suffix to the source-name hint.
+   */
+  async createView(objectName, spec) {
+    await this.connect();
+    let name = String(spec?.name || "").trim();
+    if (!name) {
+      let base = String(spec?.label || objectName || "view").toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 40);
+      if (!base || /^[0-9]/.test(base)) {
+        base = base ? `view_${base}` : "view";
+      }
+      const suffix = Date.now().toString(36);
+      name = `${base}_${suffix}`;
+    }
+    const fullSpec = {
+      ...spec,
+      name,
+      object: spec?.object || objectName,
+      data: spec?.data || { provider: "object", object: objectName }
+    };
+    try {
+      const result = await this.client.meta.saveItem("view", name, fullSpec);
+      this.metadataCache.invalidate?.(`views:${objectName}`);
+      if (result && result.item) return result.item;
+      return fullSpec;
+    } catch (err) {
+      throw err;
+    }
+  }
+  /**
+   * Apply a partial update to an existing overlay view. Reads the current
+   * overlay (or seeds from artifact), merges, and writes back. ADR-0005
+   * overlay rows store the *full* view document, so partial updates require
+   * a read-merge-write cycle.
+   */
+  async updateView(objectName, viewName, partial) {
+    await this.connect();
+    let current = {};
+    try {
+      const r = await this.client.meta.getItem("view", viewName);
+      current = r && (r.item || r) || {};
+      if (current?.list) current = current.list;
+    } catch {
+    }
+    const merged = {
+      ...current,
+      ...partial,
+      name: viewName,
+      object: current?.object || current?.data?.object || objectName
+    };
+    try {
+      const result = await this.client.meta.saveItem("view", viewName, merged);
+      this.metadataCache.invalidate?.(`views:${objectName}`);
+      this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+      if (result && result.item) return result.item;
+      return merged;
+    } catch (err) {
+      throw err;
+    }
+  }
+  /**
+   * Delete an overlay view (reset to artifact default if one exists, or
+   * remove entirely if it was a user-created view). Routes to
+   * `DELETE /api/v1/meta/view/:name`.
+   */
+  async deleteView(objectName, viewName) {
+    await this.connect();
+    try {
+      const result = await this.client.meta.deleteItem("view", viewName);
+      this.metadataCache.invalidate?.(`views:${objectName}`);
+      this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+      return { deleted: !!(result?.deleted ?? result?.reset ?? true) };
+    } catch (err) {
+      throw err;
+    }
+  }
   /**
    * Get an application definition by name or ID.
    * Attempts to fetch from the server metadata API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "4.0.9",
+  "version": "4.0.11",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -23,8 +23,8 @@
   ],
   "dependencies": {
     "@objectstack/client": "^4.0.5",
-    "@object-ui/core": "4.0.9",
-    "@object-ui/types": "4.0.9"
+    "@object-ui/core": "4.0.11",
+    "@object-ui/types": "4.0.11"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/index.ts

@@ -275,6 +275,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   // multiple sibling components requesting the same dataset on first paint)
   // into a single network round trip.
   private inflightFinds = new Map<string, Promise<QueryResult<T>>>();
+  // Resources that have responded 404 at least once (collection not installed
+  // on this backend). Subsequent find() calls short-circuit to an empty result
+  // so optional collections like sys_presence don't hammer the server with
+  // failing requests on every record open / panel render.
+  private missingResources = new Set<string>();
 
   constructor(config: {
     baseUrl: string;
@@ -470,6 +475,12 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    * Converts OData-style params to ObjectStack query options.
    */
   async find(resource: string, params?: QueryParams): Promise<QueryResult<T>> {
+    // Short-circuit when this resource has previously responded 404 — the
+    // collection isn't installed on this backend. Callers (AppHeader,
+    // RecordDetailView, …) treat empty data as "feature unavailable".
+    if (this.missingResources.has(resource)) {
+      return { data: [], total: 0 } as QueryResult<T>;
+    }
     const key = `${resource}::${stableStringify(params)}`;
     const existing = this.inflightFinds.get(key);
     if (existing) return existing;
@@ -489,8 +500,17 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       }
 
       const queryOptions = this.convertQueryParams(params);
-      const result: unknown = await this.client.data.find<T>(resource, queryOptions);
-      return this.normalizeQueryResult(result, params);
+      try {
+        const result: unknown = await this.client.data.find<T>(resource, queryOptions);
+        return this.normalizeQueryResult(result, params);
+      } catch (err) {
+        if (is404Error(err)) {
+          // Mark the resource so subsequent calls don't repeat the 404.
+          this.missingResources.add(resource);
+          return { data: [], total: 0 } as QueryResult<T>;
+        }
+        throw err;
+      }
     })();
 
     this.inflightFinds.set(key, promise);
@@ -1116,16 +1136,23 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   ): Promise<Record<string, any> | void> {
     await this.connect();
     try {
+      // ADR-0005 metadata customization overlay: persist views under
+      // `type='view'` (NOT `type=<objectName>` — that was a pre-overlay
+      // misuse that hit `/api/v1/meta/<objectName>/<viewId>`, which the
+      // server never wired). The view's `data.object` field is what
+      // associates it back to the object on read.
+      const merged = { ...(config || {}), object: (config as any)?.object || objectName, name: viewId };
       const result: any = await this.client.meta.saveItem(
-        objectName,
+        'view',
         viewId,
-        config
+        merged
       );
       // Invalidate cached read so next getView reflects the change
       const cacheKey = `view:${objectName}:${viewId}`;
       this.metadataCache.invalidate?.(cacheKey);
       // Also invalidate the batch override map so listViewOverrides re-fetches
       this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
+      this.metadataCache.invalidate?.(`views:${objectName}`);
       if (result && result.item) return result.item;
       return result ?? undefined;
     } catch (err) {
@@ -1136,6 +1163,140 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * List user-created views for a given object via the metadata overlay
+   * API (ADR-0005). Replaces the legacy `find('sys_view', {...})` path
+   * that wrote to a physical `sys_view` table whose columns no longer
+   * match the view spec shape.
+   *
+   * Returns view spec objects with their canonical `name` as identifier.
+   * Filters by `data.object === objectName` (or top-level `object`)
+   * client-side because the metadata index is name-only, not field-typed.
+   */
+  async listViews(objectName: string): Promise<any[]> {
+    await this.connect();
+    try {
+      const result: any = await this.client.meta.getItems('view');
+      const items: any[] = Array.isArray(result?.items)
+        ? result.items
+        : Array.isArray(result) ? result : [];
+      return items.filter((v: any) => {
+        if (!v) return false;
+        // Handle both bare view spec and `{list: {...}}` artifact wrapper
+        const spec = v.list ?? v;
+        const obj = spec?.data?.object ?? spec?.object ?? spec?.objectName;
+        return obj === objectName;
+      }).map((v: any) => v.list ?? v);
+    } catch (err) {
+      console.warn('[OBJECTSTACKDataSource] listViews failed:', err);
+      return [];
+    }
+  }
+
+  /**
+   * Create a new overlay view for an object. The view's `name` is the
+   * stable identifier — must be unique within the project scope. Returns
+   * the persisted view spec (or undefined when the server doesn't echo).
+   *
+   * Generates a snake_case name if `spec.name` is not provided by appending
+   * a short timestamp suffix to the source-name hint.
+   */
+  async createView(
+    objectName: string,
+    spec: Record<string, any>,
+  ): Promise<Record<string, any> | void> {
+    await this.connect();
+    let name = String(spec?.name || '').trim();
+    if (!name) {
+      let base = String(spec?.label || objectName || 'view')
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 40);
+      // Spec requires snake_case starting with a letter or underscore.
+      // Labels like "表格 1" collapse to "1" after non-ascii stripping, so we
+      // need a fallback / prefix to keep the identifier valid.
+      if (!base || /^[0-9]/.test(base)) {
+        base = base ? `view_${base}` : 'view';
+      }
+      const suffix = Date.now().toString(36);
+      name = `${base}_${suffix}`;
+    }
+    const fullSpec = {
+      ...spec,
+      name,
+      object: spec?.object || objectName,
+      data: spec?.data || { provider: 'object', object: objectName },
+    };
+    try {
+      const result: any = await this.client.meta.saveItem('view', name, fullSpec);
+      this.metadataCache.invalidate?.(`views:${objectName}`);
+      if (result && result.item) return result.item;
+      return fullSpec;
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  /**
+   * Apply a partial update to an existing overlay view. Reads the current
+   * overlay (or seeds from artifact), merges, and writes back. ADR-0005
+   * overlay rows store the *full* view document, so partial updates require
+   * a read-merge-write cycle.
+   */
+  async updateView(
+    objectName: string,
+    viewName: string,
+    partial: Record<string, any>,
+  ): Promise<Record<string, any> | void> {
+    await this.connect();
+    let current: any = {};
+    try {
+      const r: any = await this.client.meta.getItem('view', viewName);
+      current = (r && (r.item || r)) || {};
+      // Some endpoints return the bare item; others wrap as {type,name,item}
+      if (current?.list) current = current.list;
+    } catch {
+      // Treat missing as create-equivalent
+    }
+    const merged = {
+      ...current,
+      ...partial,
+      name: viewName,
+      object: current?.object || (current as any)?.data?.object || objectName,
+    };
+    try {
+      const result: any = await this.client.meta.saveItem('view', viewName, merged);
+      this.metadataCache.invalidate?.(`views:${objectName}`);
+      this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+      if (result && result.item) return result.item;
+      return merged;
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  /**
+   * Delete an overlay view (reset to artifact default if one exists, or
+   * remove entirely if it was a user-created view). Routes to
+   * `DELETE /api/v1/meta/view/:name`.
+   */
+  async deleteView(
+    objectName: string,
+    viewName: string,
+  ): Promise<{ deleted: boolean }> {
+    await this.connect();
+    try {
+      const result: any = await this.client.meta.deleteItem('view', viewName);
+      this.metadataCache.invalidate?.(`views:${objectName}`);
+      this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+      return { deleted: !!(result?.deleted ?? result?.reset ?? true) };
+    } catch (err) {
+      throw err;
+    }
+  }
+
+
   /**
    * Get an application definition by name or ID.
    * Attempts to fetch from the server metadata API.