labimotion 2.4.0.rc4 → 2.4.0.rc5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1babeffe4e43eb088d5ab781101aa48574f67aab9abf0d32df4d883742e63788
-  data.tar.gz: 8c063d368a6af316e5397804951da314d8fc65035a852f56b066097091b0b2b3
+  metadata.gz: 3e6b4cffa98971ea0ef93e54a537710c7fdc587f2433f038a54f42be1ac63f21
+  data.tar.gz: b57ba99244c3b9ec975fef1acb2c1b588b8d9bee5a5d6c356d336bc247c08738
 SHA512:
-  metadata.gz: 5d92879758e133fbf40fd433882967c8731ebf18e1e2586d8026a65b2d085359a530333cd740d00b7b0359981f155c034eee5687ffe326bb842c2dbc1ee52ad8
-  data.tar.gz: 3db447e733afbe176b1d7adb80078ef85899b473336e882d41bb9f7da4b66b51ca91d1f4084d30a0f644401e95c4312669bd1f9a6d7bc861af42dc8ad89d1abd
+  metadata.gz: c727c0b2409e463b0e6130986ebdcc528cf6473696b2124889061557f365ec163cc1393d08662b258801ddadafd16f7134e82786d759121b915e47b499814b55
+  data.tar.gz: 84ac6b69a8326012b61eae9aefef2f248c85ac22fa45cf266cf03114378a0cde2d1839f0798d3d460d35223000283db2a7ee4dcb3bdcfa4e4faac414ad01460b

data/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 * Features and enhancements:
+  * `Link Element` is now available as a column type inside `Table` fields of generic elements and segments ([chem-generic-ui#1055](https://github.com/LabIMotion/chem-generic-ui/issues/1055), labimotion#261). A `drag_element` cell stores the same payload the layer-level field stores (`el_id`, `el_klass`, `el_label`, `el_name`, `el_tip`, `icon_name`) and deliberately carries no `is_new`/`cr_opt`: a drop links a record that already exists and must never create one on save, unlike the sample column it sits next to. The stored label, name, tooltip and icon are refreshed on every read by the new `Labimotion::Serializer.set_table_element`, called from `PropertiesEntity` and `ElnElementEntity` as well, so all three property loaders agree rather than drifting into three copies. `SampleAssociation.build_table_element` writes the `Labimotion::ElementsElement` join rows and feeds the same `els` list that the stale-link cleanup compares against — feeding it is load-bearing, since the cleanup would otherwise `destroy_all` the rows it had just created. Both paths skip a cell whose `el_klass` is a `Labimotion::LinkedElement::MODELS` key: such a column accepts reactions, wellplates, screens and the rest as readily as generic elements, and for those `el_id` is not a `Labimotion::Element` id, so resolving it would relabel or link a wholly unrelated element — the same guard the layer-level field already applies. Carried through every export path: XLSX (`exporter_helpers`, expandable like the sample and molecule columns, short label as the cell text and `Name` as an optional sub-column), DOCX (`export_element`), and the ZIP round-trip (`export_utils` remaps element ids to uuids, `import_utils` re-links them through the new `proc_table_element`). A linked element has no structure image, so the cell shows the klass icon instead of an SVG.
+  * Element cover images, write path ([chem-generic-ui#1050](https://github.com/LabIMotion/chem-generic-ui/issues/1050), labimotion#259): the element create and update saves now validate the `cover_images` key of the optional `metadata` param — an array of at most 3 `{ source: attachment|analysis, id: <integer> }` references, mirroring the chem-generic-ui picker's cap and vocabulary, normalized to exactly those two entry keys — and refuse a malformed selection with a plain 422 before any container/sample-association write runs. All cover-image helpers live in the dedicated `Labimotion::CoverImageHelpers` module, with the contract cap and source vocabulary as `Constants::CoverImage::MAX`/`SOURCES`. The rest of the metadata document keeps its existing contract: a present param replaces the stored hash wholesale, because its other writers (layer groups/restrictions from the details page, host regComps through the registry seam) remove a key by omitting it, while an absent param leaves stored metadata untouched — an old client that does not send `metadata` can never wipe a saved cover selection. References only, no FK: a deleted attachment/analysis leaves a dangling reference the UI skips at render time. No migration (`elements.metadata` and `elements_revisions.metadata` already exist), no entity change (`metadata` was already exposed), no klass change (the per-klass `cover_image` toggle rides the existing `update_settings` shallow merge); revision snapshots already carry `metadata` alongside `properties`, and restoring a revision round-trips the cover selection through this validated save.
+  * Element cover images, original serving ([chem-generic-ui#1050](https://github.com/LabIMotion/chem-generic-ui/issues/1050), labimotion#259): new `GET /generic_elements/cover_image?element_id=&source=&id=` answers the original file behind a cover-image reference, so the element page's display area can show originals while thumbnails stay in the picker. Gated by the `genericElement` matrix check plus `ElementPolicy` `read?` **and** `read_dataset?` (analysis previews are dataset attachments, and the ELN's own attachment reads demand both); the reference resolves through the element's own associations only, so a foreign attachment or container id answers 404, never a file. An `analysis` reference resolves the container preview server-side for the first time, mirroring the client's `getContainerImageData`: the container's `preferred_thumbnail` while it still exists, else the newest "combined" image, else the newest thumbnail-bearing dataset attachment. The body is the original bytes under the file's own content type — or the PNG thumbnail when a browser could not render the original (TIFF, raw-data files behind an analysis preview). An optional `variant=thumbnail` always answers the PNG thumbnail through the same gate and resolution, which is what the picker's rows show — for an svg the stored thumbnail (black: ImageMagick reads `transparent` as black) is replaced by a fresh white-background rasterization of the original, through the same shared converter as the docx export — with it, the whole cover-image feature runs on gem-owned API surface and the host wires no fetcher at all. The picker's Save persists directly through the new `POST /generic_elements/cover_images` (`element_id`, `cover_images`; gated by `ElementPolicy` `update?` + the matrix check): the same validation as the element-save path, then a **targeted merge** of exactly the `cover_images` key into the stored metadata — deliberately narrower than the element save's wholesale-replace contract, so this writer can neither wipe nor resurrect `groups`/host keys. Live like klass settings: the write is immediate and unversioned until the next element save snapshots metadata into the revisions. The docx export (`ExportElement`) now renders the cover selection too: the stored references resolve through the same helpers as the `cover_image` endpoint, each image is embedded above the layers (originals for the rasters Word renders reliably — png/jpeg/gif/bmp; other renderable originals such as svg are rasterized onto white via MiniMagick, with the CSS keyword `transparent` normalized to `none` first because ImageMagick’s own SVG renderer reads it as black — the PNG thumbnail only as last resort), captioned "ref: …" and scaled to the page via MiniMagick-read dimensions (best effort — without them the template placeholder geometry is kept), Requires the matching `Labimotion_lines.docx` template change in the host ELN (a `has_cover`-guarded `cover_images:each` block before the layers loop); an old template simply ignores the new context keys.
   * Share notifications now fire from the gem itself ([chem-generic-ui#1040](https://github.com/LabIMotion/chem-generic-ui/issues/1040), labimotion#255): a successful grant or level change (`POST /generic_klass/shares`), an ownership transfer (`POST /generic_klass/transfer_ownership`) and the ask that creates an access-request row (`POST /generic_klass/request_access`, `created: true` only — repeat asks are not repeat pings) each send the toast the host's `Chemotion::TemplateShareAPI` used to send, through the new `Labimotion::ShareNotifier`. Recipients are Persons only, never the actor; the channel is looked up by the literal subject `'Template Share Notification'` (the host ELN's channel migration stays required for delivery); and the notifier rescues internally — an undeliverable notification is a notification not sent, never a failed share. A host without Message/Channel machinery (or without the channel row) silently sends nothing. The level-change route (`PUT /shares/:id`) stays silent, matching the host layer it replaces. Until the matching ELN change removes `TemplateShareAPI` and its caller, grants on the integration branches notify twice — accepted, dev-only.
   * Per-template ownership and sharing, backend ([chem-generic-ui#1001](https://github.com/LabIMotion/chem-generic-ui/issues/1001) Phase 2): `klass_shares` table (viewer/editor/owner, one owner per template enforced by a partial unique index), `authorize_klass!` per-template gate replacing the designer-wide check on template mutation endpoints (owner-less templates keep the legacy behaviour permanently), share management endpoints under `/generic_klass/shares` plus `/generic_klass/transfer_ownership`, and capability booleans (`can_write` … `can_manage`) on the Designer list payloads. `download_klass` is now gated (`:read`) and no longer writes an identifier during a GET. Requires host ELN twin migrations `create_klass_shares` and `seed_klass_share_owners` (the latter seeds owner rows from `created_by` in raw SQL, idempotent via `ON CONFLICT DO NOTHING`); deploy order is migrate → **restart** (the stale schema cache otherwise silently drops the running app's writes to the new table). Ships as one upgrade with the matching chem-generic-ui and ELN changes — see the design doc's ADR 0001.
   * `created_by` and `created_at` are now `NOT NULL` on `element_klasses` and `segment_klasses` ([chem-generic-ui#1018](https://github.com/LabIMotion/chem-generic-ui/issues/1018)); `dataset_klasses` already declared both. Two new migrations, back-dated ahead of `create_klass_shares`: `backfill_klass_created_columns` fills a NULL `created_by` with the first system administrator (falling back to the lowest-id user of any type, and raising if the `users` table is empty) and a NULL `created_at` with `COALESCE(updated_at, NOW())`; `tighten_klass_created_columns` then applies the constraints — data before constraint. The back-dating is what lets `seed_klass_share_owners` stay unchanged: with `created_by` already filled in, its `WHERE created_by IS NOT NULL` filter excludes nothing and every template gets an owner row instead of staying owner-less on the permanent legacy gate. The backfill re-runs that owner seed itself (`ON CONFLICT DO NOTHING`) so a database on which the seed had already run picks up the repaired rows. Requires host ELN twin migrations for both, back-dated the same way; deploy order is migrate → **restart** (the stale schema cache otherwise silently drops the running app's writes).

data/lib/labimotion/apis/generic_dataset_api.rb

@@ -7,7 +7,6 @@ module Labimotion
 
     helpers Labimotion::GenericHelpers
     helpers Labimotion::DatasetHelpers
-    helpers Labimotion::ParamHelpers
 
     resource :generic_dataset do
       namespace :klasses do
@@ -79,34 +78,6 @@ module Labimotion
         end
       end
 
-      namespace :create_ai_klass do
-        desc 'create a Generic Dataset Klass from an AI-generated template'
-        params do
-          use :create_ai_dataset_klass_params
-        end
-        post do
-          msg = create_ai_dataset_klass(params, current_user)
-          klass = Labimotion::DatasetKlassEntity.represent(Labimotion::DatasetKlass.all)
-          { status: msg[:status], message: msg[:message], klass: klass }
-        rescue StandardError => e
-          Labimotion.log_exception(e, current_user)
-          { error: e.message }
-        end
-      end
-
-      namespace :refine_ai_klass do
-        desc 'refine a Generic Dataset Klass template with AI (returns the revised template; not persisted)'
-        params do
-          use :refine_ai_dataset_klass_params
-        end
-        post do
-          refine_ai_dataset_klass(params, current_user)
-        rescue StandardError => e
-          Labimotion.log_exception(e, current_user)
-          { status: 'error', message: e.message }
-        end
-      end
-
       namespace :find_template do
         desc 'Find best matching template for given OLS term ID'
         params do

data/lib/labimotion/apis/generic_element_api.rb

@@ -16,6 +16,7 @@ module Labimotion
     helpers Labimotion::VocabularyHelpers
     helpers Labimotion::GenericHelpers
     helpers Labimotion::ElementHelpers
+    helpers Labimotion::CoverImageHelpers
     helpers Labimotion::ParamHelpers
 
     resource :generic_elements do
@@ -108,6 +109,31 @@ module Labimotion
           Labimotion.log_exception(e, current_user)
           { attributes: [], error: e.message }
         end
+
+        desc 'List the selectable inline attributes of a klass, with no element instance'
+        params do
+          requires :el_klass, type: String, desc: 'Generic klass name or permit-target key (reaction, sample, ...)'
+        end
+        get 'for_klass' do
+          error!('401 Unauthorized', 401) unless current_user
+
+          # Template shape only — no instance is read, so there is nothing
+          # collection-scoped to authorize beyond being a signed-in user.
+          { attributes: Labimotion::LinkedElement.available_for_klass(params[:el_klass]) }
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { attributes: [], error: e.message }
+        end
+
+        desc 'List the standard ELN element types a drag field can link'
+        get 'permit_targets' do
+          error!('401 Unauthorized', 401) unless current_user
+
+          { permit_targets: Labimotion::LinkedElement.permit_targets }
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { permit_targets: [], error: e.message }
+        end
       end
 
       namespace :search_basic_by_like do
@@ -186,43 +212,6 @@ module Labimotion
         end
       end
 
-      namespace :create_ai_klass do
-        desc 'create a Generic Element Klass from an AI-generated template'
-        params do
-          use :create_ai_element_klass_params
-        end
-        post do
-          authenticate_admin!('elements')
-          msg = create_ai_element_klass(params, current_user)
-          { status: msg[:status], message: msg[:message],
-            klass: Labimotion::ElementKlassEntity.represent(Labimotion::ElementKlass.where(is_active: true)) }
-        rescue StandardError => e
-          Labimotion.log_exception(e, current_user)
-          { error: e.message }
-        end
-      end
-
-      # Sibling namespace of :create_ai_klass — MUST stay above the route_param :id
-      # blocks below, otherwise POST /ai_fill_data falls through to the element
-      # instance route and Element.find(nil) is raised.
-      namespace :ai_fill_data do
-        desc "Auto-fill a generic element's data values from a document using AI"
-        params do
-          use :ai_fill_element_data_params
-        end
-        post do
-          msg = ai_fill_element_data(params, current_user)
-          if msg[:status] == 'success'
-            { status: 'success', values: msg[:values], summary: msg[:summary] }
-          else
-            { status: 'error', message: msg[:message] }
-          end
-        rescue StandardError => e
-          Labimotion.log_exception(e, current_user)
-          { status: 'error', message: e.message }
-        end
-      end
-
       namespace :update_element_klass do
         desc 'update Generic Element Klass'
         params do
@@ -530,6 +519,58 @@ module Labimotion
         { generic_elements: [] }
       end
 
+      # Declared before `route_param :id` so the literal segment is not
+      # swallowed by the id capture.
+      namespace :cover_images do
+        desc 'Save the cover-image selection directly (live, like klass settings)'
+        params do
+          requires :element_id, type: Integer, desc: 'Element id'
+          requires :cover_images, type: Array, desc: 'Ordered {source, id} references; [] clears'
+        end
+        post do
+          element = Labimotion::Element.find(params[:element_id])
+          unless current_user.matrix_check_by_name('genericElement') &&
+                 ElementPolicy.new(current_user, element).update?
+            error!('401 Unauthorized', 401)
+          end
+
+          { mc: 'ss00', cover_images: save_cover_images(element, params[:cover_images]) }
+        rescue ActiveRecord::RecordNotFound
+          error!('404 Not Found', 404)
+        end
+      end
+
+      namespace :cover_image do
+        desc 'Serve the image behind a cover-image reference (original or thumbnail)'
+        params do
+          requires :element_id, type: Integer, desc: 'Element id'
+          requires :source, type: String, values: Labimotion::Constants::CoverImage::SOURCES,
+                            desc: 'Reference source'
+          requires :id, type: Integer, desc: 'Attachment or analysis-container id'
+          optional :variant, type: String, values: %w[original thumbnail], default: 'original',
+                             desc: 'original file (display area) or PNG thumbnail (picker rows)'
+        end
+        get do
+          element = Labimotion::Element.find(params[:element_id])
+          policy = ElementPolicy.new(current_user, element)
+          unless current_user.matrix_check_by_name('genericElement') && policy.read? && policy.read_dataset?
+            error!('401 Unauthorized', 401)
+          end
+
+          attachment = cover_image_attachment(element, params[:source], params[:id])
+          payload = attachment && cover_image_body(attachment, params[:variant])
+          error!('404 Not Found', 404) if payload.nil?
+
+          data, mime_type = payload
+          env['api.format'] = :binary
+          content_type(mime_type || 'application/octet-stream')
+          header('Content-Disposition', "inline; filename=\"#{CGI.escape(attachment.filename.to_s)}\"")
+          data
+        rescue ActiveRecord::RecordNotFound
+          error!('404 Not Found', 404)
+        end
+      end
+
       desc 'Return serialized element by id'
       params do
         requires :id, type: Integer, desc: 'Element id'
@@ -547,6 +588,7 @@ module Labimotion
           {
             element: Labimotion::ElementEntity.represent(
               element,
+              current_user: current_user,
               detail_levels: ElementDetailLevelCalculator.new(user: current_user, element: element).detail_levels,
               policy: @element_policy
             ),
@@ -591,6 +633,7 @@ module Labimotion
             {
               element: Labimotion::ElementEntity.represent(
                 element,
+                current_user: current_user,
                 detail_levels: ElementDetailLevelCalculator.new(user: current_user, element: element).detail_levels,
               ),
               attachments: Entities::AttachmentEntity.represent(element&.attachments),

data/lib/labimotion/apis/segment_api.rb

@@ -59,25 +59,6 @@ module Labimotion
         end
       end
 
-      namespace :create_ai_klass do
-        desc 'create a Generic Segment Klass from an AI-generated template'
-        params do
-          use :create_ai_segment_klass_params
-        end
-        after_validation do
-          authenticate_admin!('segments')
-          @klass = fetch_klass('ElementKlass', params[:element_klass])
-        end
-        post do
-          msg = create_ai_segment_klass(current_user, params)
-          { status: msg[:status], message: msg[:message],
-            klass: Labimotion::SegmentKlassEntity.represent(Labimotion::SegmentKlass.all) }
-        rescue StandardError => e
-          Labimotion.log_exception(e, current_user)
-          { error: e.message }
-        end
-      end
-
       namespace :update_segment_klass do
         desc 'update Generic Segment Klass'
         params do

data/lib/labimotion/apis/user_klass_settings_api.rb

@@ -3,7 +3,8 @@
 require 'labimotion/version'
 
 module Labimotion
-  # Per-user, per-klass UI settings API (toolbar Overview/Arrange visibility).
+  # Per-user, per-klass UI settings API (toolbar Overview/Arrange visibility, and
+  # the default inline attributes of a linked element).
   # Every route is scoped to the authenticated user via created_by, so a user
   # only ever reads/writes their own setting; no klass-edit permission needed.
   class UserKlassSettingsAPI < Grape::API
@@ -14,15 +15,37 @@ module Labimotion
         Labimotion::UserKlassSetting.where(created_by: current_user.id)
       end
 
-      def klass_toolbar(settings)
-        (settings || {})['toolbar'] || (settings || {})[:toolbar] || {}
+      # Only the sub-settings actually present in the request are written, so a
+      # save carrying just one of them leaves the other untouched. Absent reads
+      # as "leave alone"; an empty linked_el_attrs array reads as "clear".
+      def submitted_settings(settings)
+        settings = (settings || {}).transform_keys(&:to_s)
+        toolbar = settings[Labimotion::Constants::UserSetting::TOOLBAR]
+        attrs = settings[Labimotion::Constants::UserSetting::LINKED_EL_ATTRS]
+        {}.tap do |result|
+          result[Labimotion::Constants::UserSetting::TOOLBAR] = toolbar if toolbar.is_a?(Hash)
+          if attrs.is_a?(Array)
+            result[Labimotion::Constants::UserSetting::LINKED_EL_ATTRS] = normalize_linked_el_attrs(attrs)
+          end
+        end
+      end
+
+      # Persist only the identity of each attribute. The values are resolved live
+      # on every load, and the label is refreshed from the template alongside them.
+      def normalize_linked_el_attrs(attrs)
+        attrs.filter_map do |attr|
+          attr = attr.transform_keys(&:to_s) if attr.respond_to?(:transform_keys)
+          next unless attr.is_a?(Hash) && attr['key'].present?
+
+          { 'source' => attr['source'], 'key' => attr['key'], 'label' => attr['label'] }
+        end
       end
     end
 
     resource :user_klass_settings do
       desc 'Fetch the current user UI setting for a klass'
       params do
-        requires :klass, type: String, values: %w[ElementKlass SegmentKlass DatasetKlass], desc: 'Klass type'
+        requires :klass, type: String, values: Labimotion::Constants::Klass::USER_SETTINGS, desc: 'Klass type'
         requires :identifier, type: String, desc: 'Klass identifier'
       end
       get 'fetch' do
@@ -48,7 +71,7 @@ module Labimotion
         )
         record.klass_label = params[:klass_label] if params[:klass_label]
         record.created_by ||= current_user.id
-        record.settings = (record.settings || {}).merge('toolbar' => klass_toolbar(params[:settings]))
+        record.settings = (record.settings || {}).merge(submitted_settings(params[:settings]))
         record.save!
         { mc: 'ss00', data: Labimotion::UserKlassSettingEntity.represent(record) }
       rescue StandardError => e

data/lib/labimotion/constants.rb

@@ -17,6 +17,14 @@ module Labimotion
       CV = 'Cyclic Voltammetry'
     end
 
+    # The element cover selection (labimotion#259): cap and source vocabulary
+    # of `metadata.cover_images` entries. Mirrored by the chem-generic-ui
+    # cover-image picker (chem-generic-ui#1050) — keep them in sync.
+    module CoverImage
+      SOURCES = %w[attachment analysis].freeze
+      MAX = 3
+    end
+
     module Mapper
       NMR_CONFIG = ::File.join(__dir__, 'libs', 'data', 'mapper', 'Source.json').freeze
       WIKI_CONFIG = ::File.join(__dir__, 'libs', 'data', 'mapper', 'Chemwiki.json').freeze
@@ -27,6 +35,20 @@ module Labimotion
       SEGMENT = 'SegmentKlass'
       DATASET = 'DatasetKlass'
       ALL = [ELEMENT, SEGMENT, DATASET].freeze
+
+      # Standard ELN elements (sample, reaction, molecule, ...) have no klass
+      # model. Per-user settings that key on one use this pseudo-type, with the
+      # permit-target key itself as the klass identifier — see
+      # Labimotion::UserKlassSetting.
+      PERMIT_TARGET = 'PermitTarget'
+      USER_SETTINGS = [ELEMENT, SEGMENT, DATASET, PERMIT_TARGET].freeze
+    end
+
+    # The independent sub-settings held side by side in
+    # user_klass_settings.settings. A save writes only the ones it carries.
+    module UserSetting
+      TOOLBAR = 'toolbar'
+      LINKED_EL_ATTRS = 'linked_el_attrs'
     end
 
     # The designer-right families as keyed in `users.generic_admin` (host-owned jsonb) and

data/lib/labimotion/entities/eln_element_entity.rb

@@ -68,6 +68,12 @@ module Labimotion
             object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx] =
               set_table(field, field_table_samples, Labimotion::Prop::SAMPLE)
           end
+
+          field_table_elements = field[Labimotion::Prop::SUBFIELDS].select { |ss| ss['type'] == Labimotion::FieldType::DRAG_ELEMENT }
+          if field_table_elements.present?
+            object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx] =
+              Labimotion::Serializer.set_table_element(field, field_table_elements)
+          end
         end
       end
       object.properties

data/lib/labimotion/entities/properties_entity.rb

@@ -97,15 +97,55 @@ module Labimotion
       return unless field['value'].is_a?(Hash)
 
       attrs = field.dig('value', 'el_attrs')
+      el_klass = field.dig('value', 'el_klass')
+      el_id = field.dig('value', 'el_id')
+      el_type = field.dig('value', 'el_type')
+      linked = Labimotion::LinkedElement.new(el_klass, el_id, el_type)
+
+      # A missing el_attrs means the user never picked anything for this link, so
+      # their My LabIMotion default applies. An explicit [] means they picked none
+      # — the two must not collapse, or clearing a selection would not stick.
+      from_default = attrs.nil?
+      attrs = default_linked_attrs(el_klass, el_type) if from_default
       return unless attrs.is_a?(Array) && attrs.present?
       return unless object.properties.dig(Labimotion::Prop::LAYERS, key, Labimotion::Prop::FIELDS, idx,
                                           'value').present?
 
-      el_klass = field.dig('value', 'el_klass')
-      el_id = field.dig('value', 'el_id')
-      el_type = field.dig('value', 'el_type')
-      object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx]['value']['el_attrs'] =
-        Labimotion::LinkedElement.new(el_klass, el_id, el_type).resolve(attrs)
+      resolved = linked.resolve(attrs)
+      resolved = resolved.map { |attr| mark_default(attr) } if from_default
+      object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx]['value']['el_attrs'] = resolved
+    end
+
+    def mark_default(attr)
+      attr.is_a?(Hash) ? attr.merge(Labimotion::LinkedElement::IS_DEFAULT => true) : attr
+    end
+
+    # Keyed by what the drag field itself stores — el_klass for a generic element
+    # or a standard type, el_type for drag_molecule, which omits el_klass. Read
+    # straight off the preloaded map rather than via LinkedElement#target_key, so
+    # a field with no default costs no query.
+    def default_linked_attrs(el_klass, el_type)
+      map = default_linked_attrs_map
+      return [] if map.empty?
+
+      map[el_klass.to_s] || map[el_type.to_s] || []
+    end
+
+    # The current user's defaults for every linked target, loaded once per
+    # represented object. Skipped when no user is in scope (this entity is also
+    # rendered from contexts that pass none, e.g. Hub submissions and exports) and
+    # for list views, which don't render the inline attributes and would otherwise
+    # pay the lookup once per row.
+    def default_linked_attrs_map
+      return @default_linked_attrs_map if defined?(@default_linked_attrs_map)
+
+      user_id = options[:current_user]&.id
+      @default_linked_attrs_map =
+        if user_id.blank? || displayed_in_list?
+          {}
+        else
+          Labimotion::UserKlassSetting.linked_el_attrs_by_el_klass(user_id)
+        end
     end
 
     def update_reaction_field(key, field, idx)
@@ -144,10 +184,18 @@ module Labimotion
       field_table_samples = field[Labimotion::Prop::SUBFIELDS].select do |ss|
         ss['type'] == Labimotion::FieldType::DRAG_SAMPLE
       end
-      return unless field_table_samples.present?
+      if field_table_samples.present?
+        object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx] =
+          set_table(field, field_table_samples, Labimotion::Prop::SAMPLE)
+      end
+
+      field_table_elements = field[Labimotion::Prop::SUBFIELDS].select do |ss|
+        ss['type'] == Labimotion::FieldType::DRAG_ELEMENT
+      end
+      return unless field_table_elements.present?
 
       object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx] =
-        set_table(field, field_table_samples, Labimotion::Prop::SAMPLE)
+        Labimotion::Serializer.set_table_element(field, field_table_elements)
     end
 
     def update_voc_field(key, field, idx)

data/lib/labimotion/helpers/cover_image_helpers.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'grape'
+require 'labimotion/constants'
+
+module Labimotion
+  ## Element cover images (chem-generic-ui#1050, labimotion#259).
+  ## `cover_images` is the one element-metadata key whose shape the gem owns:
+  ## validation and normalization of the stored references, their direct
+  ## save, the resolution of a reference to the attachment holding its
+  ## picture, and the bytes served for the display area (originals), the
+  ## picker rows (thumbnails) and the docx export.
+  module CoverImageHelpers
+    extend Grape::API::Helpers
+
+    # Element metadata is a client-round-tripped document with several writers —
+    # layer groups/restrictions from the element details page, host regComps
+    # through the registry seam — and those writers remove a key by omitting it.
+    # So a present :metadata param replaces the stored hash wholesale; only an
+    # absent param leaves the stored metadata untouched (an old client that does
+    # not send :metadata must never wipe a saved cover selection). `cover_images`
+    # is the one key the gem owns: its entries are validated against the picker's
+    # cap and source vocabulary and normalized to exactly source/id, so nothing
+    # else reaches the jsonb column through that key.
+    def prepare_element_metadata(stored, incoming)
+      return stored || {} if incoming.nil?
+
+      # to_h returns self for a plain Hash — dup so the caller's copy stays intact.
+      metadata = incoming.to_h.dup
+      return metadata unless metadata.key?('cover_images') || metadata.key?(:cover_images)
+
+      entries = metadata.key?('cover_images') ? metadata['cover_images'] : metadata[:cover_images]
+      metadata.delete(:cover_images)
+      metadata['cover_images'] = validate_cover_images!(entries)
+      metadata
+    end
+
+    def validate_cover_images!(entries)
+      cover_images_error!('must be an array') unless entries.is_a?(Array)
+      max = Constants::CoverImage::MAX
+      cover_images_error!("holds at most #{max} entries") if entries.size > max
+
+      entries.map { |entry| normalized_cover_image!(entry) }
+    end
+
+    def normalized_cover_image!(entry)
+      cover_image_entry_error! unless entry.is_a?(Hash)
+      source = entry['source'] || entry[:source]
+      id = entry['id'] || entry[:id]
+      cover_image_entry_error! unless Constants::CoverImage::SOURCES.include?(source) && id.is_a?(Integer)
+      { 'source' => source, 'id' => id }
+    end
+
+    def cover_image_entry_error!
+      cover_images_error!("entries must be { source: #{Constants::CoverImage::SOURCES.join(' | ')}, id: integer }")
+    end
+
+    def cover_images_error!(reason)
+      error!("metadata.cover_images #{reason}", 422)
+    end
+
+    # Direct write of the one gem-owned metadata key (the cover picker's
+    # Save): a targeted merge, deliberately narrower than the element save's
+    # wholesale-replace contract — this writer owns exactly cover_images and
+    # can neither wipe nor resurrect any other key. Live like klass settings:
+    # not versioned until the next element save snapshots metadata.
+    def save_cover_images(element, entries)
+      validated = validate_cover_images!(entries)
+      element.update!(metadata: (element.metadata || {}).merge('cover_images' => validated))
+      validated
+    end
+
+    # Resolves a stored cover-image reference to the Attachment holding its
+    # picture, or nil. Ownership is part of the resolution: an attachment is
+    # looked up through the element's own association, an analysis must be one
+    # of the element's analyses — a foreign id answers nil, never a file.
+    def cover_image_attachment(element, source, sid)
+      case source
+      when 'attachment'
+        element.attachments.find_by(id: sid)
+      when 'analysis'
+        container = element.analyses.find_by(id: sid)
+        container && analysis_preview_attachment(container)
+      end
+    end
+
+    # Server twin of the ELN client's getContainerImageData: among the
+    # thumbnail-bearing attachments of the analysis' dataset children, the
+    # container's preferred_thumbnail wins while it still exists, then the
+    # newest "combined" image, then the newest overall.
+    def analysis_preview_attachment(container)
+      dataset_ids = container.children.where(container_type: 'dataset').pluck(:id)
+      return nil if dataset_ids.empty?
+
+      candidates = Attachment.where(attachable_type: 'Container', attachable_id: dataset_ids, thumb: true).to_a
+      pick_preview_attachment(container, candidates)
+    end
+
+    def pick_preview_attachment(container, candidates)
+      return nil if candidates.empty?
+
+      preferred = preferred_candidate(container, candidates)
+      return preferred if preferred
+
+      combined = candidates.select { |att| att.filename.to_s.downcase.include?('combined') }
+      (combined.empty? ? candidates : combined).max_by(&:updated_at)
+    end
+
+    # hstore values are strings — the stored preferred_thumbnail id arrives as '1'.
+    def preferred_candidate(container, candidates)
+      preferred_id = (container.extended_metadata || {})['preferred_thumbnail'].to_i
+      candidates.find { |att| att.id == preferred_id }
+    end
+
+    # The picker's rows ask for variant=thumbnail — the small uniform PNG;
+    # everything else means the original (display area). An svg's STORED
+    # thumbnail is black (see cover_rasterize), so it is re-rasterized from
+    # the original instead, falling back to the stored one.
+    def cover_image_body(att, variant)
+      return cover_image_payload(att) unless variant == 'thumbnail'
+
+      thumb = svg_cover_thumbnail(att) || att.read_thumbnail
+      [thumb, 'image/png'] if thumb
+    end
+
+    COVER_THUMB_RESIZE = '256x256>'
+
+    def svg_cover_thumbnail(att)
+      mime = att.content_type.to_s.downcase
+      return nil unless mime.include?('svg')
+
+      data = att.read_file
+      data && cover_rasterize(data, mime, resize: COVER_THUMB_RESIZE)
+    end
+
+    ## ImageMagick's own SVG renderer reads the CSS keyword `transparent` as
+    ## black — the defect behind the ELN thumbnails' black background — so
+    ## paint properties are normalized to `none` first and the result is a
+    ## PNG flattened onto white. Nil when conversion is unavailable or
+    ## fails; callers fall back.
+    SVG_TRANSPARENT_RE =
+      /((?:fill|stroke|stop-color|flood-color|background(?:-color)?)\s*[:=]\s*["']?)transparent\b/i
+
+    def cover_rasterize(data, mime, resize: nil)
+      # Deferred on purpose: mini_magick is a host-bundle gem, not a
+      # dependency of this gem — at the top of the file it would break gem
+      # load (and the spec suite) on a host without it, while here a miss is
+      # rescued below into the nil fallback.
+      require 'mini_magick'
+      data = data.gsub(SVG_TRANSPARENT_RE, '\1none') if mime.include?('svg')
+      image = MiniMagick::Image.read(data, cover_read_ext(mime))
+      image.format('png') do |convert|
+        convert.background('white')
+        convert.flatten
+        convert.resize(resize) if resize
+      end
+      image.to_blob
+    rescue LoadError, StandardError => e
+      Labimotion.log_exception(e)
+      nil
+    end
+
+    def cover_read_ext(mime)
+      subtype = mime.split('/').last.to_s.sub('+xml', '')
+      subtype.empty? ? '.img' : ".#{subtype}"
+    end
+
+    # The bytes + content type to serve for a cover attachment: the original
+    # file whenever a browser can render it, otherwise the PNG thumbnail
+    # (TIFF originals, raw-data files behind an analysis preview). Nil when
+    # neither is readable.
+    def cover_image_payload(att)
+      if att.type_image? && !att.type_image_tiff?
+        data = att.read_file
+        return [data, att.content_type] if data
+      end
+      thumb = att.read_thumbnail
+      [thumb, 'image/png'] if thumb
+    end
+  end
+end