velocious 1.0.445 → 1.0.447

package/src/frontend-models/base.js

@@ -24,10 +24,22 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  * Defines this typedef.
  * @typedef {{type: "hasOne" | "hasMany"}} FrontendModelAttachmentDefinition
  */
+/**
+ * Attachment input accepted by frontend-model attachment helpers before normalization.
+ * @typedef {Record<string, ?> | {arrayBuffer: () => Promise<ArrayBuffer>, type?: string, name?: string} | null | undefined} FrontendModelAttachmentInput
+ */
 /**
  * Defines this typedef.
  * @typedef {{attributes?: string[], builtInCollectionCommands?: string[], builtInMemberCommands?: string[], collectionCommands?: string[], commands?: string[], memberCommands?: string[], attachments?: Record<string, FrontendModelAttachmentDefinition>, modelName?: string, nestedAttributes?: Record<string, {allowDestroy?: boolean, limit?: number}>, primaryKey?: string, relationships?: string[]}} FrontendModelResourceConfig
  */
+/**
+ * Frontend model constructor type.
+ * @typedef {{new (attributes?: Record<string, ?>): FrontendModelBase}} FrontendModelConstructor
+ */
+/**
+ * Frontend model static side without generated per-model create overloads.
+ * @typedef {FrontendModelConstructor & Omit<typeof FrontendModelBase, "create">} FrontendModelClass
+ */
 /**
  * FrontendModelTransportConfig type.
  * @typedef {object} FrontendModelTransportConfig
@@ -57,7 +69,7 @@ const QUERY_DATA_KEY = "__queryData"
 const ABILITIES_KEY = "__abilities"
 /**
  * Pending shared frontend model requests.
-  @type {Array<{commandName?: string, commandType: FrontendModelRequestCommandType, customPath?: string, modelClass: typeof FrontendModelBase, payload: Record<string, ?>, requestId: string, resolve: (response: Record<string, ?>) => void, reject: (error: ?) => void, resourcePath?: string | null}>} */
+  @type {Array<{commandName?: string, commandType: FrontendModelRequestCommandType, customPath?: string, modelClass: FrontendModelClass, payload: Record<string, ?>, requestId: string, resolve: (response: Record<string, ?>) => void, reject: (error: ?) => void, resourcePath?: string | null}>} */
 let pendingSharedFrontendModelRequests = []
 let sharedFrontendModelRequestId = 0
 let sharedFrontendModelFlushScheduled = false
@@ -204,7 +216,7 @@ async function flushBufferedOutgoingEventsAfterReconnect() {
 
 /**
  * Runs default frontend model resource path.
- * @param {typeof FrontendModelBase} modelClass - Frontend model class.
+ * @param {FrontendModelClass} modelClass - Frontend model class.
  * @returns {string} - Default resource path for the model class.
  */
 function defaultFrontendModelResourcePath(modelClass) {
@@ -226,8 +238,8 @@ export class AttributeNotSelectedError extends Error {
 
 /**
  * Lightweight singular relationship state holder for frontend model instances.
- * @template {typeof FrontendModelBase} S
- * @template {typeof FrontendModelBase} T
+ * @template {FrontendModelClass} S
+ * @template {FrontendModelClass} T
  */
 export class FrontendModelSingularRelationship {
   /**
@@ -296,8 +308,8 @@ export class FrontendModelSingularRelationship {
 
 /**
  * Lightweight has-many relationship state holder for frontend model instances.
- * @template {typeof FrontendModelBase} S
- * @template {typeof FrontendModelBase} T
+ * @template {FrontendModelClass} S
+ * @template {FrontendModelClass} T
  */
 export class FrontendModelHasManyRelationship {
   /**
@@ -614,6 +626,17 @@ function frontendModelPayloadContainsAttachmentUpload(value) {
   return Object.values(value).some((entry) => frontendModelPayloadContainsAttachmentUpload(entry))
 }
 
+/**
+ * Returns the concrete frontend-model class for an instance.
+ * @param {FrontendModelBase} model - Frontend model instance.
+ * @returns {FrontendModelClass} Concrete frontend-model class.
+ */
+function frontendModelClassFor(model) {
+  const constructorValue = model.constructor
+
+  return /** @type {FrontendModelClass} */ (constructorValue)
+}
+
 /**
  * Runs normalize frontend attachment input.
  * @param {?} input - Attachment input.
@@ -691,6 +714,12 @@ async function normalizeFrontendAttachmentInput(input) {
  * Frontend-model attachment helper for one attachment name.
  */
 export class FrontendModelAttachmentHandle {
+  /**
+   * Pending attachment inputs queued for the next model save.
+   * @type {FrontendModelAttachmentInput[]}
+   */
+  pendingInputs = []
+
   /**
    * Runs constructor.
    * @param {object} args - Options.
@@ -702,15 +731,70 @@ export class FrontendModelAttachmentHandle {
     this.attachmentName = attachmentName
   }
 
+  /**
+   * Queue attachment input for the parent model's next save.
+   * @param {FrontendModelAttachmentInput | FrontendModelAttachmentInput[]} input - Attachment input.
+   * @returns {void}
+   */
+  queueAttach(input) {
+    const ModelClass = frontendModelClassFor(this.model)
+    const attachmentDefinition = ModelClass.attachmentDefinition(this.attachmentName)
+
+    if (attachmentDefinition?.type === "hasOne") {
+      if (Array.isArray(input)) {
+        const lastInput = input[input.length - 1]
+
+        this.pendingInputs = typeof lastInput === "undefined" ? [] : [lastInput]
+      } else {
+        this.pendingInputs = [input]
+      }
+      return
+    }
+
+    if (Array.isArray(input)) {
+      this.pendingInputs.push(...input)
+    } else {
+      this.pendingInputs.push(input)
+    }
+  }
+
+  /**
+   * Whether this attachment has queued inputs for the next model save.
+   * @returns {boolean} Whether any pending inputs exist.
+   */
+  hasPendingAttachments() {
+    return this.pendingInputs.length > 0
+  }
+
+  /**
+   * Builds the save payload for queued attachment inputs.
+   * @returns {Promise<Record<string, ?> | Record<string, ?>[] | undefined>} Normalized attachment payload.
+   */
+  async pendingAttachmentsPayload() {
+    if (this.pendingInputs.length === 0) return undefined
+
+    const ModelClass = frontendModelClassFor(this.model)
+    const attachmentDefinition = ModelClass.attachmentDefinition(this.attachmentName)
+
+    if (attachmentDefinition?.type === "hasMany") {
+      return await Promise.all(this.pendingInputs.map(async (input) => await normalizeFrontendAttachmentInput(input)))
+    }
+
+    return await normalizeFrontendAttachmentInput(this.pendingInputs[this.pendingInputs.length - 1])
+  }
+
+  /** Clears queued attachment inputs after a successful model save. */
+  clearPendingAttachments() {
+    this.pendingInputs = []
+  }
+
   /**
    * Runs attach.
    * @param {?} input - Attachment input.
    * @returns {Promise<void>} - Resolves when attached.
    */
   async attach(input) {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.model.constructor)
+    const ModelClass = frontendModelClassFor(this.model)
     const normalizedInput = await normalizeFrontendAttachmentInput(input)
     const response = await ModelClass.executeCommand("attach", {
       attachment: normalizedInput,
@@ -727,9 +811,7 @@ export class FrontendModelAttachmentHandle {
    * @returns {Promise<FrontendModelAttachmentDownload | null>} - Downloaded attachment payload.
    */
   async download(attachmentId) {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.model.constructor)
+    const ModelClass = frontendModelClassFor(this.model)
     const response = await ModelClass.executeCommand("download", frontendModelAttachmentCommandPayload(this, attachmentId))
     const attachmentPayload = response.attachment
 
@@ -755,9 +837,7 @@ export class FrontendModelAttachmentHandle {
    * @returns {Promise<string | null>} - Resolvable attachment URL.
    */
   async url(attachmentId) {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.model.constructor)
+    const ModelClass = frontendModelClassFor(this.model)
     const response = await ModelClass.executeCommand("url", frontendModelAttachmentCommandPayload(this, attachmentId))
 
     if (typeof response.url === "string" && response.url.length > 0) {
@@ -772,9 +852,7 @@ export class FrontendModelAttachmentHandle {
    * @returns {string} - Download URL for this attachment on the configured backend.
    */
   downloadUrl() {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.model.constructor)
+    const ModelClass = frontendModelClassFor(this.model)
     const commandName = ModelClass.commandName("download")
     const resourcePath = ModelClass.resourcePath()
     const commandUrl = frontendModelCommandUrl(resourcePath, commandName)
@@ -831,7 +909,7 @@ const FRONTEND_MODELS_CHANNEL_NAME = "frontend-models"
 
 /**
  * Defines this typedef.
- * @typedef {{callback: (payload: {id: string, model: InstanceType<typeof FrontendModelBase>}) => void, eventFilterKey: string | null, eventFilterPayload: import("./query.js").FrontendModelEventFilterPayload | null, projectionPayload: import("./query.js").FrontendModelProjectionPayload}} FrontendModelModelEventCallbackEntry
+ * @typedef {{callback: (payload: {id: string, model: FrontendModelBase}) => void, eventFilterKey: string | null, eventFilterPayload: import("./query.js").FrontendModelEventFilterPayload | null, projectionPayload: import("./query.js").FrontendModelProjectionPayload}} FrontendModelModelEventCallbackEntry
  */
 /**
  * Defines this typedef.
@@ -981,7 +1059,7 @@ function frontendModelEventEntryMatches(entry, matchedEventFilterKeys) {
 
 /**
  * Runs assert no destroy event filter.
- * @param {typeof FrontendModelBase} ModelClass - Event model class.
+ * @param {FrontendModelClass} ModelClass - Event model class.
  * @param {import("./query.js").FrontendModelEventOptions} options - Event options.
  * @returns {void}
  */
@@ -1007,7 +1085,7 @@ function assertNoDestroyEventFilter(ModelClass, options) {
 class FrontendModelEventSubscription {
   /**
    * Runs constructor.
-   * @param {typeof FrontendModelBase} ModelClass - Frontend model class for this subscription bucket.
+   * @param {FrontendModelClass} ModelClass - Frontend model class for this subscription bucket.
    */
   constructor(ModelClass) {
     this.ModelClass = ModelClass
@@ -1025,7 +1103,7 @@ class FrontendModelEventSubscription {
     this.classDestroyCallbacks = new Set()
     /**
      * Narrows the runtime value to the documented type.
-      @type {Map<string, {instance: InstanceType<typeof FrontendModelBase>, updateCallbacks: Set<FrontendModelModelEventCallbackEntry>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry>}>} */
+      @type {Map<string, {instance: FrontendModelBase, updateCallbacks: Set<FrontendModelModelEventCallbackEntry>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry>}>} */
     this.instanceListeners = new Map()
     /**
      * Narrows the runtime value to the documented type.
@@ -1263,12 +1341,12 @@ class FrontendModelEventSubscription {
 
 /**
  * Frontend model event subscriptions.
-  @type {WeakMap<typeof FrontendModelBase, FrontendModelEventSubscription>} */
+  @type {WeakMap<FrontendModelClass, FrontendModelEventSubscription>} */
 const frontendModelEventSubscriptions = new WeakMap()
 
 /**
  * Runs ensure frontend model event subscription.
- * @param {typeof FrontendModelBase} ModelClass - Model class.
+ * @param {FrontendModelClass} ModelClass - Model class.
  * @returns {FrontendModelEventSubscription} - Per-class subscription helper.
  */
 function ensureFrontendModelEventSubscription(ModelClass) {
@@ -1286,8 +1364,8 @@ function ensureFrontendModelEventSubscription(ModelClass) {
  * Runs ensure frontend model instance listener.
  * @param {FrontendModelEventSubscription} sub - Event subscription bucket.
  * @param {string} id - Model id.
- * @param {InstanceType<typeof FrontendModelBase>} instance - Listener instance.
- * @returns {{instance: InstanceType<typeof FrontendModelBase>, updateCallbacks: Set<FrontendModelModelEventCallbackEntry>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry>}} - Instance listener bucket.
+ * @param {FrontendModelBase} instance - Listener instance.
+ * @returns {{instance: FrontendModelBase, updateCallbacks: Set<FrontendModelModelEventCallbackEntry>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry>}} - Instance listener bucket.
  */
 function ensureFrontendModelInstanceListener(sub, id, instance) {
   let listener = sub.instanceListeners.get(id)
@@ -1648,12 +1726,17 @@ export default class FrontendModelBase {
   _attributes
   /**
    * Narrows the runtime value to the documented type.
-    @type {Record<string, FrontendModelHasManyRelationship<typeof FrontendModelBase, typeof FrontendModelBase> | FrontendModelSingularRelationship<typeof FrontendModelBase, typeof FrontendModelBase>>} */
+    @type {Record<string, FrontendModelHasManyRelationship<FrontendModelClass, FrontendModelClass> | FrontendModelSingularRelationship<FrontendModelClass, FrontendModelClass>>} */
   _relationships
   /**
    * Narrows the runtime value to the documented type.
     @type {Record<string, FrontendModelAttachmentHandle>} */
   _attachments
+  /**
+   * Rails-style nested attribute payloads queued for the next save.
+   * @type {Record<string, ?>}
+   */
+  _pendingNestedAttributes
   /**
    * Narrows the runtime value to the documented type.
     @type {Set<string> | null} */
@@ -1681,14 +1764,13 @@ export default class FrontendModelBase {
    * @param {Record<string, ?>} [attributes] - Initial attributes.
    */
   constructor(attributes = {}) {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
 
     ModelClass.ensureGeneratedAttachmentMethods()
     this._attributes = {}
     this._relationships = {}
     this._attachments = {}
+    this._pendingNestedAttributes = {}
     this._selectedAttributes = null
     this._isNewRecord = true
     this._markedForDestruction = false
@@ -1698,7 +1780,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs ensure generated attachment methods.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @returns {void} - Ensures attachment helper methods exist on the prototype.
    */
   static ensureGeneratedAttachmentMethods() {
@@ -1732,8 +1814,8 @@ export default class FrontendModelBase {
 
   /**
    * Runs relationship model classes.
-   * @this {typeof FrontendModelBase}
-   * @returns {Record<string, typeof FrontendModelBase | string>} - Relationship model classes (or class name strings) keyed by relationship name.
+   * @this {FrontendModelClass}
+   * @returns {Record<string, FrontendModelClass | string>} - Relationship model classes (or class name strings) keyed by relationship name.
    */
   static relationshipModelClasses() {
     return {}
@@ -1741,7 +1823,7 @@ export default class FrontendModelBase {
 
   /**
    * Register a frontend model class so it can be resolved by name in relationship lookups.
-   * @param {typeof FrontendModelBase} modelClass - Model class to register.
+   * @param {FrontendModelClass} modelClass - Model class to register.
    * @returns {void}
    */
   static registerModel(modelClass) {
@@ -1751,7 +1833,7 @@ export default class FrontendModelBase {
   /**
    * Runs define scope.
    * @param {(...args: Array<?>) => ?} callback - Scope callback.
-   * @returns {((...args: Array<?>) => import("./query.js").default<typeof FrontendModelBase>) & {scope: (...args: Array<?>) => import("../utils/model-scope.js").ModelScopeDescriptor}} - Scope helper.
+   * @returns {((...args: Array<?>) => import("./query.js").default<FrontendModelClass>) & {scope: (...args: Array<?>) => import("../utils/model-scope.js").ModelScopeDescriptor}} - Scope helper.
    */
   static defineScope(callback) {
     return defineModelScope({
@@ -1763,8 +1845,8 @@ export default class FrontendModelBase {
 
   /**
    * Resolve a relationship model class value that may be a class reference or a string name.
-   * @param {typeof FrontendModelBase | string | null | undefined} value - Class or class name.
-   * @returns {typeof FrontendModelBase | null} - Resolved model class.
+   * @param {FrontendModelClass | string | null | undefined} value - Class or class name.
+   * @returns {FrontendModelClass | null} - Resolved model class.
    */
   static resolveModelClass(value) {
     return resolveFrontendModelClass(value)
@@ -1772,7 +1854,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs relationship definitions.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @returns {Record<string, {type: "belongsTo" | "hasOne" | "hasMany", autoload?: boolean}>} - Relationship definitions keyed by relationship name.
    */
   static relationshipDefinitions() {
@@ -1781,7 +1863,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs attachment definitions.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @returns {Record<string, FrontendModelAttachmentDefinition>} - Attachment definitions keyed by attachment name.
    */
   static attachmentDefinitions() {
@@ -1790,7 +1872,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs attachment definition.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {string} attachmentName - Attachment name.
    * @returns {FrontendModelAttachmentDefinition | null} - Attachment definition.
    */
@@ -1800,7 +1882,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs relationship definition.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {string} relationshipName - Relationship name.
    * @returns {{type: "belongsTo" | "hasOne" | "hasMany", autoload?: boolean} | null} - Relationship definition.
    */
@@ -1810,11 +1892,28 @@ export default class FrontendModelBase {
     return definitions[relationshipName] || null
   }
 
+  /**
+   * Resolves a Rails-style nested attributes key to a configured relationship.
+   * @this {FrontendModelClass}
+   * @param {string} attributeName - Candidate attribute name, such as `tasksAttributes`.
+   * @returns {string | null} Relationship name when nested attributes are configured.
+   */
+  static nestedAttributesRelationshipName(attributeName) {
+    if (!attributeName.endsWith("Attributes")) return null
+
+    const relationshipName = attributeName.slice(0, -"Attributes".length)
+    const nestedAttributesConfig = this.resourceConfig().nestedAttributes || {}
+
+    return Object.prototype.hasOwnProperty.call(nestedAttributesConfig, relationshipName)
+      ? relationshipName
+      : null
+  }
+
   /**
    * Runs relationship model class.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {string} relationshipName - Relationship name.
-   * @returns {typeof FrontendModelBase | null} - Target relationship model class.
+   * @returns {FrontendModelClass | null} - Target relationship model class.
    */
   static relationshipModelClass(relationshipName) {
     const relationshipModelClasses = this.relationshipModelClasses()
@@ -1911,13 +2010,11 @@ export default class FrontendModelBase {
   /**
    * Runs get relationship by name.
    * @param {string} relationshipName - Relationship name.
-   * @returns {FrontendModelHasManyRelationship<typeof FrontendModelBase, typeof FrontendModelBase> | FrontendModelSingularRelationship<typeof FrontendModelBase, typeof FrontendModelBase>} - Relationship state object.
+   * @returns {FrontendModelHasManyRelationship<FrontendModelClass, FrontendModelClass> | FrontendModelSingularRelationship<FrontendModelClass, FrontendModelClass>} - Relationship state object.
    */
   getRelationshipByName(relationshipName) {
     if (!this._relationships[relationshipName]) {
-      const ModelClass = /**
-                          * Narrows the runtime value to the documented type.
-                           @type {typeof FrontendModelBase} */ (this.constructor)
+      const ModelClass = frontendModelClassFor(this)
       const relationshipDefinition = ModelClass.relationshipDefinition(relationshipName)
       const targetModelClass = ModelClass.relationshipModelClass(relationshipName)
 
@@ -1937,9 +2034,7 @@ export default class FrontendModelBase {
    * @returns {FrontendModelAttachmentHandle} - Attachment helper.
    */
   getAttachmentByName(attachmentName) {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
     const attachmentDefinition = ModelClass.attachmentDefinition(attachmentName)
 
     if (!attachmentDefinition) {
@@ -1962,9 +2057,7 @@ export default class FrontendModelBase {
    * @returns {Promise<?>} - Loaded relationship value.
    */
   async loadRelationship(relationshipName) {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
     const id = this.primaryKeyValue()
     const reloadedModel = await ModelClass
       .preload([relationshipName])
@@ -1983,7 +2076,7 @@ export default class FrontendModelBase {
    * required columns present are left untouched unless `force` is set. Carries
    * the query's preload graph, select, selectsExtra, withCount, abilities, and
    * queryData when re-fetching.
-   * @param {import("./query.js").default<typeof FrontendModelBase> | import("../database/query/index.js").NestedPreloadRecord | string | Array<string | import("../database/query/index.js").NestedPreloadRecord>} queryOrSpec - Preload source.
+   * @param {import("./query.js").default<FrontendModelClass> | import("../database/query/index.js").NestedPreloadRecord | string | Array<string | import("../database/query/index.js").NestedPreloadRecord>} queryOrSpec - Preload source.
    * @param {{force?: boolean}} [options] - Options.
    * @returns {Promise<void>} - Resolves when preloading completes.
    */
@@ -2024,9 +2117,7 @@ export default class FrontendModelBase {
   async _tryCohortPreload(relationshipName) {
     if (!FrontendModelBase.getAutoload()) return false
 
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
     const cohort = this._loadCohort
 
     if (!cohort || cohort.length <= 1) return false
@@ -2101,9 +2192,7 @@ export default class FrontendModelBase {
    * @returns {?} - Assigned relationship value.
    */
   setRelationship(relationshipName, relationshipValue) {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
     const relationshipDefinition = ModelClass.relationshipDefinition(relationshipName)
 
     if (!relationshipDefinition) {
@@ -2140,7 +2229,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs primary key.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @returns {string} - Primary key name.
    */
   static primaryKey() {
@@ -2152,9 +2241,7 @@ export default class FrontendModelBase {
    * @returns {number | string} - Primary key value.
    */
   primaryKeyValue() {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
     const value = this.readAttribute(ModelClass.primaryKey())
 
     if (value === undefined || value === null) {
@@ -2296,6 +2383,19 @@ export default class FrontendModelBase {
    * @returns {?} - Assigned value.
    */
   setAttribute(attributeName, newValue) {
+    const ModelClass = frontendModelClassFor(this)
+    const nestedAttributesRelationshipName = ModelClass.nestedAttributesRelationshipName(attributeName)
+
+    if (nestedAttributesRelationshipName) {
+      this._pendingNestedAttributes[nestedAttributesRelationshipName] = newValue
+      return newValue
+    }
+
+    if (ModelClass.attachmentDefinition(attributeName)) {
+      this.getAttachmentByName(attributeName).queueAttach(newValue)
+      return newValue
+    }
+
     const previousValue = this._attributes[attributeName]
 
     this._attributes[attributeName] = newValue
@@ -2330,9 +2430,7 @@ export default class FrontendModelBase {
   _invalidateRelationshipsForAttribute(attributeName) {
     if (!this._relationships || Object.keys(this._relationships).length === 0) return
 
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
     const definitions = typeof ModelClass.relationshipDefinitions === "function" ? ModelClass.relationshipDefinitions() : {}
 
     for (const relationshipName of Object.keys(this._relationships)) {
@@ -2352,7 +2450,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs resource path.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @returns {string} - Derived resource path.
    */
   static resourcePath() {
@@ -2364,7 +2462,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs command name.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {FrontendModelCommandType} commandType - Command type.
    * @returns {string} - Resolved command name.
    */
@@ -2385,7 +2483,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs normalize custom command payload arguments.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {Array<?>} args - Command arguments.
    * @returns {Record<string, ?>} - Command payload.
    */
@@ -2420,7 +2518,7 @@ export default class FrontendModelBase {
    * Returns the model name, preferring an explicit `static modelName` declaration
    * over the JavaScript class `.name` property. This allows minified builds to
    * preserve correct model names without relying on `keep_classnames`.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @returns {string} - The model name.
    */
   static getModelName() {
@@ -2712,7 +2810,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs attributes from response.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {object} response - Response payload.
    * @returns {Record<string, ?>} - Attributes from payload.
    */
@@ -2724,7 +2822,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs model data from response.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {object} response - Response payload.
    * @returns {{abilities: Record<string, boolean>, attributes: Record<string, ?>, associationCounts: Record<string, number>, queryData: Record<string, ?>, preloadedRelationships: Record<string, ?>, selectedAttributes: Set<string>}} - Attributes, preloaded relationships, association counts, queryData, abilities, and the selected-attributes set.
    */
@@ -2794,7 +2892,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs apply preloaded relationships.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {FrontendModelBase} model - Model instance.
    * @param {Record<string, ?>} preloadedRelationships - Preloaded relationship payload.
    * @returns {void}
@@ -2815,9 +2913,9 @@ export default class FrontendModelBase {
 
   /**
    * Runs instantiate relationship value.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {?} relationshipPayload - Relationship payload value.
-   * @param {typeof FrontendModelBase | null} targetModelClass - Target model class.
+   * @param {FrontendModelClass | null} targetModelClass - Target model class.
    * @returns {?} - Instantiated relationship value.
    */
   static instantiateRelationshipValue(relationshipPayload, targetModelClass) {
@@ -2830,7 +2928,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs instantiate from response.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {Record<string, ?> | InstanceType<T>} response - Response payload, or an already-hydrated instance of this class.
    * @returns {InstanceType<T>} - New model instance, or the same instance unchanged if it was already hydrated.
@@ -2883,7 +2981,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs find.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {number | string} id - Record identifier.
    * @returns {Promise<InstanceType<T>>} - Resolved model.
@@ -2894,7 +2992,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs find by.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {Record<string, ?>} conditions - Attribute match conditions.
    * @returns {Promise<InstanceType<T> | null>} - Found model or null.
@@ -2905,7 +3003,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs find by or fail.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {Record<string, ?>} conditions - Attribute match conditions.
    * @returns {Promise<InstanceType<T>>} - Found model.
@@ -2916,7 +3014,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs to array.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @returns {Promise<InstanceType<T>[]>} - Loaded model instances.
    */
@@ -2926,7 +3024,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs load.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @returns {Promise<InstanceType<T>[]>} - Loaded model instances.
    */
@@ -2936,7 +3034,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs all.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @returns {FrontendModelQuery<T>} - Query builder.
    */
@@ -2946,7 +3044,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs where.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {Record<string, ?>} conditions - Root-model where conditions.
    * @returns {import("./query.js").default<T>} - Query with where conditions.
@@ -2957,7 +3055,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs joins.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {Record<string, ?> | Array<Record<string, ?>>} joins - Relationship descriptor joins.
    * @returns {import("./query.js").default<T>} - Query with joins.
@@ -2968,7 +3066,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs limit.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {number} value - Maximum number of records.
    * @returns {import("./query.js").default<T>} - Query with limit.
@@ -2979,7 +3077,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs offset.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {number} value - Number of records to skip.
    * @returns {import("./query.js").default<T>} - Query with offset.
@@ -2990,7 +3088,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs page.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {number} pageNumber - 1-based page number.
    * @returns {import("./query.js").default<T>} - Query with page applied.
@@ -3001,7 +3099,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs per page.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {number} value - Number of records per page.
    * @returns {import("./query.js").default<T>} - Query with page size.
@@ -3012,7 +3110,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs count.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @returns {Promise<number>} - Number of loaded model instances.
    */
@@ -3026,8 +3124,8 @@ export default class FrontendModelBase {
    * accepted, future `create` events for this model are delivered
    * without re-checking per-record visibility. Query options can still
    * narrow which events reach this callback.
-   * @this {typeof FrontendModelBase}
-   * @param {(payload: {id: string, model: InstanceType<typeof FrontendModelBase>}) => void} callback - Event callback.
+   * @this {FrontendModelClass}
+   * @param {(payload: {id: string, model: FrontendModelBase}) => void} callback - Event callback.
    * @param {import("./query.js").FrontendModelEventOptions} [options] - Event query or record projection options.
    * @returns {Promise<() => void>} - Unsubscribe callback.
    */
@@ -3046,8 +3144,8 @@ export default class FrontendModelBase {
 
   /**
    * Class-level hook fired when any record of this model is updated.
-   * @this {typeof FrontendModelBase}
-   * @param {(payload: {id: string, model: InstanceType<typeof FrontendModelBase>}) => void} callback - Event callback.
+   * @this {FrontendModelClass}
+   * @param {(payload: {id: string, model: FrontendModelBase}) => void} callback - Event callback.
    * @param {import("./query.js").FrontendModelEventOptions} [options] - Event query or record projection options.
    * @returns {Promise<() => void>} - Unsubscribe callback.
    */
@@ -3066,7 +3164,7 @@ export default class FrontendModelBase {
 
   /**
    * Class-level hook fired when any record of this model is destroyed.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {(payload: {id: string}) => void} callback - Event callback.
    * @param {import("./query.js").FrontendModelEventOptions} [options] - Accepted for API symmetry; destroy events carry ids only.
    * @returns {Promise<() => void>} - Unsubscribe callback.
@@ -3091,7 +3189,7 @@ export default class FrontendModelBase {
    * instance's attributes are auto-merged with the broadcast payload
    * before the callback runs, so callers can read fresh values via
    * `this.someAttr()` without re-fetching.
-   * @param {(payload: {id: string, model: InstanceType<typeof FrontendModelBase>}) => void} callback - Event callback.
+   * @param {(payload: {id: string, model: FrontendModelBase}) => void} callback - Event callback.
    * @param {import("./query.js").FrontendModelEventOptions} [options] - Event query or record projection options.
    * @returns {Promise<() => void>} - Unsubscribe callback.
    */
@@ -3099,9 +3197,7 @@ export default class FrontendModelBase {
     const self = /**
                   * Narrows the runtime value to the documented type.
                    @type {?} */ (this)
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
     const sub = ensureFrontendModelEventSubscription(ModelClass)
     const id = String(self.id())
     const entry = {callback, ...frontendModelEventOptionsPayload(ModelClass, options)}
@@ -3133,9 +3229,7 @@ export default class FrontendModelBase {
     const self = /**
                   * Narrows the runtime value to the documented type.
                    @type {?} */ (this)
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
 
     assertNoDestroyEventFilter(ModelClass, options)
 
@@ -3162,7 +3256,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs pluck.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {...(string | string[] | Record<string, ?> | Array<Record<string, ?>>)} columns - Pluck definition(s).
    * @returns {Promise<Array<?>>} - Plucked values.
@@ -3173,7 +3267,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs search.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {string[]} path - Relationship path.
    * @param {string} column - Column or attribute name.
@@ -3187,7 +3281,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs ransack.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {Record<string, ?>} params - Ransack-style params hash.
    * @returns {FrontendModelQuery<T>} - Query builder with Ransack filters applied.
@@ -3198,7 +3292,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs sort.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {string | string[] | string[][] | [string, string] | Array<[string, string]> | Record<string, ?> | Array<Record<string, ?>>} sort - Sort definition(s).
    * @returns {FrontendModelQuery<T>} - Query builder with sort definitions.
@@ -3209,7 +3303,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs order.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {string | string[] | string[][] | [string, string] | Array<[string, string]> | Record<string, ?> | Array<Record<string, ?>>} sort - Sort definition(s).
    * @returns {FrontendModelQuery<T>} - Query builder with sort definitions.
@@ -3220,7 +3314,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs group.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {string | string[] | Record<string, ?> | Array<Record<string, ?>>} group - Group definition(s).
    * @returns {FrontendModelQuery<T>} - Query builder with group definitions.
@@ -3231,7 +3325,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs distinct.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {boolean} [value] - Whether to request distinct rows.
    * @returns {FrontendModelQuery<T>} - Query builder with distinct flag.
@@ -3242,7 +3336,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs query.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @returns {FrontendModelQuery<T>} - Query builder.
    */
@@ -3252,7 +3346,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs preload.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {import("../database/query/index.js").NestedPreloadRecord | string | Array<string | import("../database/query/index.js").NestedPreloadRecord>} preload - Preload graph.
    * @returns {FrontendModelQuery<T>} - Query with preload.
@@ -3263,7 +3357,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs select.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {Record<string, string[] | string> | string | string[]} select - Model-aware attribute select map or root-model shorthand.
    * @returns {FrontendModelQuery<T>} - Query with selected attributes.
@@ -3274,7 +3368,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs selects extra.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {Record<string, string[] | string> | string | string[]} select - Extra attributes to load in addition to the defaults, keyed by model name or root-model shorthand.
    * @returns {FrontendModelQuery<T>} - Query with extra selected attributes.
@@ -3285,7 +3379,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs first.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @returns {Promise<InstanceType<T> | null>} - First model or null.
    */
@@ -3295,7 +3389,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs last.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @returns {Promise<InstanceType<T> | null>} - Last model or null.
    */
@@ -3305,7 +3399,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs find or initialize by.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {Record<string, ?>} conditions - Attribute match conditions.
    * @returns {Promise<InstanceType<T>>} - Existing or initialized model.
@@ -3316,7 +3410,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs find or create by.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {Record<string, ?>} conditions - Attribute match conditions.
    * @param {(model: InstanceType<T>) => Promise<void> | void} [callback] - Optional callback before save when created.
@@ -3328,7 +3422,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs create.
-   * @template {typeof FrontendModelBase} T
+   * @template {FrontendModelClass} T
    * @this {T}
    * @param {Record<string, ?>} [attributes] - Initial attributes.
    * @returns {Promise<InstanceType<T>>} - Persisted model.
@@ -3345,7 +3439,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs assert find by conditions.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {Record<string, ?>} conditions - findBy conditions.
    * @returns {void}
    */
@@ -3359,7 +3453,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs matches find by conditions.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {FrontendModelBase} model - Candidate model.
    * @param {Record<string, ?>} conditions - Match conditions.
    * @returns {boolean} - Whether the model matches all conditions.
@@ -3389,7 +3483,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs find by condition value matches.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {?} actualValue - Actual model value.
    * @param {?} expectedValue - Expected find condition value.
    * @returns {boolean} - Whether values match.
@@ -3457,7 +3551,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs find by primitive values match.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {?} actualValue - Actual model value.
    * @param {?} expectedValue - Expected find condition value.
    * @returns {boolean} - Whether primitive values match after safe coercion.
@@ -3488,7 +3582,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs find by numeric string matches number.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {string} numericString - Numeric string value.
    * @param {number} expectedNumber - Number value.
    * @returns {boolean} - Whether values represent the same number.
@@ -3511,50 +3605,9 @@ export default class FrontendModelBase {
    * @returns {Promise<this>} - Updated model.
    */
   async update(newAttributes = {}) {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
-    const attachmentDefinitions = ModelClass.attachmentDefinitions()
-    /**
-     * Regular attributes.
-      @type {Record<string, ?>} */
-    const regularAttributes = {}
-    /**
-     * Pending attachments.
-      @type {Array<{attachmentName: string, value: ?}>} */
-    const pendingAttachments = []
-
-    for (const [attributeName, attributeValue] of Object.entries(newAttributes)) {
-      if (attachmentDefinitions[attributeName]) {
-        if (attributeValue !== undefined && attributeValue !== null) {
-          pendingAttachments.push({attachmentName: attributeName, value: attributeValue})
-        }
-      } else {
-        regularAttributes[attributeName] = attributeValue
-      }
-    }
-
-    if (Object.keys(regularAttributes).length > 0) {
-      this.assignAttributes(regularAttributes)
-      const changedAttributes = Object.fromEntries(
-        Object.entries(this.changes()).map(([attributeName, [, currentValue]]) => [attributeName, currentValue])
-      )
-
-      const response = await ModelClass.executeCommand("update", {
-        attributes: changedAttributes,
-        id: this.primaryKeyValue()
-      })
-
-      this.assignAttributes(ModelClass.attributesFromResponse(response))
-      this.setIsNewRecord(false)
-      this._persistedAttributes = cloneFrontendModelAttributes(this.attributes())
-    }
+    this.assignAttributes(newAttributes)
 
-    for (const pendingAttachment of pendingAttachments) {
-      await this.getAttachmentByName(pendingAttachment.attachmentName).attach(pendingAttachment.value)
-    }
-
-    return this
+    return await this.save()
   }
 
   /**
@@ -3563,9 +3616,7 @@ export default class FrontendModelBase {
    * @returns {Promise<void>} - Resolves when attached.
    */
   async attach(attachmentInput) {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
     const attachmentDefinitions = ModelClass.attachmentDefinitions()
     const attachmentNames = Object.keys(attachmentDefinitions)
     let attachmentName = attachmentNames[0]
@@ -3597,9 +3648,7 @@ export default class FrontendModelBase {
    * @returns {Promise<this>} - Saved model.
    */
   async save() {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
     const isNew = this.isNewRecord()
     const commandType = isNew ? "create" : "update"
     /**
@@ -3613,17 +3662,25 @@ export default class FrontendModelBase {
       payload.id = this.primaryKeyValue()
     }
 
-    const nestedAttributes = this._buildNestedAttributesPayload()
+    const nestedAttributes = await this._buildNestedAttributesPayload()
 
     if (nestedAttributes && Object.keys(nestedAttributes).length > 0) {
       payload.nestedAttributes = nestedAttributes
     }
 
+    const attachments = await this._buildAttachmentsPayload()
+
+    if (Object.keys(attachments).length > 0) {
+      payload.attachments = attachments
+    }
+
     const response = await ModelClass.executeCommand(commandType, payload)
 
     this.assignAttributes(ModelClass.attributesFromResponse(response))
     this.setIsNewRecord(false)
     this._persistedAttributes = cloneFrontendModelAttributes(this.attributes())
+    this._pendingNestedAttributes = {}
+    this._clearPendingAttachments()
 
     this._reconcileNestedAttributesFromResponse(response)
 
@@ -3668,15 +3725,39 @@ export default class FrontendModelBase {
    * @returns {Promise<void>} - Resolves when destroyed on backend.
    */
   async destroy() {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
 
     await ModelClass.executeCommand("destroy", {
       id: this.primaryKeyValue()
     })
   }
 
+  /**
+   * Builds the attachment payload queued on this model for the next save.
+   * @returns {Promise<Record<string, ?>>} Attachment payload keyed by attachment name.
+   */
+  async _buildAttachmentsPayload() {
+    /** @type {Record<string, ?>} */
+    const payload = {}
+
+    for (const attachmentName of Object.keys(this._attachments)) {
+      const attachmentPayload = await this._attachments[attachmentName].pendingAttachmentsPayload()
+
+      if (attachmentPayload !== undefined) {
+        payload[attachmentName] = attachmentPayload
+      }
+    }
+
+    return payload
+  }
+
+  /** Clears queued attachment inputs after a successful save. */
+  _clearPendingAttachments() {
+    for (const attachmentName of Object.keys(this._attachments)) {
+      this._attachments[attachmentName].clearPendingAttachments()
+    }
+  }
+
   /**
    * Walks relationships declared in this resource's `nestedAttributes` config
    * and builds the per-relationship payload of dirty children for a parent save.
@@ -3689,12 +3770,10 @@ export default class FrontendModelBase {
    *
    * Loaded but untouched records are omitted so nested save preserves Rails-style
    * "children not referenced in payload are left alone" semantics.
-   * @returns {Record<string, Array<Record<string, ?>>>} - Per-relationship list of nested-attribute entries.
+   * @returns {Promise<Record<string, Array<Record<string, ?>>>>} - Per-relationship list of nested-attribute entries.
    */
-  _buildNestedAttributesPayload() {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+  async _buildNestedAttributesPayload() {
+    const ModelClass = frontendModelClassFor(this)
     const resourceConfig = typeof ModelClass.resourceConfig === "function" ? ModelClass.resourceConfig() : null
     const nestedAttributesConfig = resourceConfig?.nestedAttributes
 
@@ -3706,20 +3785,34 @@ export default class FrontendModelBase {
     const payload = {}
 
     for (const relationshipName of Object.keys(nestedAttributesConfig)) {
+      /** @type {Array<Record<string, ?>>} */
+      const entries = []
       const relationship = this._relationships[relationshipName]
 
-      if (!relationship || !(relationship instanceof FrontendModelHasManyRelationship)) continue
-      if (!Array.isArray(relationship._loadedValue) || relationship._loadedValue.length === 0) continue
+      if (relationship instanceof FrontendModelHasManyRelationship && Array.isArray(relationship._loadedValue)) {
+        for (const child of relationship._loadedValue) {
+          const childEntry = await child._nestedAttributesEntryForParentSave()
 
-      /**
-       * Entries.
-        @type {Array<Record<string, ?>>} */
-      const entries = []
+          if (childEntry) entries.push(childEntry)
+        }
+      } else if (relationship instanceof FrontendModelSingularRelationship && relationship.getPreloaded()) {
+        const child = relationship.loaded()
 
-      for (const child of relationship._loadedValue) {
-        const childEntry = child._nestedAttributesEntryForParentSave()
+        if (child instanceof FrontendModelBase) {
+          const childEntry = await child._nestedAttributesEntryForParentSave()
 
-        if (childEntry) entries.push(childEntry)
+          if (childEntry) entries.push(childEntry)
+        }
+      }
+
+      if (Object.prototype.hasOwnProperty.call(this._pendingNestedAttributes, relationshipName)) {
+        entries.push(
+          ...await this._nestedAttributesPayloadForSubmittedValue(
+            ModelClass,
+            relationshipName,
+            this._pendingNestedAttributes[relationshipName]
+          )
+        )
       }
 
       if (entries.length > 0) {
@@ -3734,41 +3827,164 @@ export default class FrontendModelBase {
    * Builds the payload entry for this child when walked by a parent's
    * `_buildNestedAttributesPayload`. Returns `null` when the child has no
    * dirty state and no dirty descendants, so the parent can omit it.
-   * @returns {Record<string, ?> | null} - Nested-attribute entry or null if clean.
+   * @returns {Promise<Record<string, ?> | null>} - Nested-attribute entry or null if clean.
    */
-  _nestedAttributesEntryForParentSave() {
+  async _nestedAttributesEntryForParentSave() {
     if (this.markedForDestruction()) {
       if (this.isNewRecord()) return null
       return {id: this.primaryKeyValue(), _destroy: true}
     }
 
-    const nestedAttributes = this._buildNestedAttributesPayload()
+    const nestedAttributes = await this._buildNestedAttributesPayload()
     const hasNestedDirty = Object.keys(nestedAttributes).length > 0
+    const attachments = await this._buildAttachmentsPayload()
+    const hasAttachments = Object.keys(attachments).length > 0
 
     if (this.isNewRecord()) {
       /**
        * Entry.
         @type {Record<string, ?>} */
-      const entry = {attributes: this.attributes()}
+      const entry = {}
+      const attributes = this._changedAttributesForSave()
 
+      if (Object.keys(attributes).length > 0) entry.attributes = attributes
+      if (hasAttachments) entry.attachments = attachments
       if (hasNestedDirty) entry.nestedAttributes = nestedAttributes
 
       return entry
     }
 
-    if (!this.isChanged() && !hasNestedDirty) return null
+    if (!this.isChanged() && !hasNestedDirty && !hasAttachments) return null
 
     /**
      * Entry.
       @type {Record<string, ?>} */
     const entry = {id: this.primaryKeyValue()}
 
-    if (this.isChanged()) entry.attributes = this.attributes()
+    if (this.isChanged()) entry.attributes = this._changedAttributesForSave()
+    if (hasAttachments) entry.attachments = attachments
     if (hasNestedDirty) entry.nestedAttributes = nestedAttributes
 
     return entry
   }
 
+  /**
+   * Builds nested entries from a Rails-style submitted `*Attributes` value.
+   * @param {FrontendModelClass} ModelClass - Parent model class.
+   * @param {string} relationshipName - Nested relationship name.
+   * @param {?} value - Submitted nested attributes value.
+   * @returns {Promise<Array<Record<string, ?>>>} Nested entries for the transport payload.
+   */
+  async _nestedAttributesPayloadForSubmittedValue(ModelClass, relationshipName, value) {
+    const relationshipDefinition = ModelClass.relationshipDefinition(relationshipName)
+    const TargetModelClass = ModelClass.relationshipModelClass(relationshipName)
+
+    if (!relationshipDefinition) {
+      throw new Error(`Unknown nested relationship: ${ModelClass.name}#${relationshipName}`)
+    }
+    if (!TargetModelClass) {
+      throw new Error(`No target model class configured for ${ModelClass.name}#${relationshipName}`)
+    }
+
+    if (relationshipTypeIsCollection(relationshipDefinition.type)) {
+      if (!Array.isArray(value)) {
+        throw new Error(`${ModelClass.name}#${relationshipName}Attributes must be an array`)
+      }
+
+      return await Promise.all(
+        value.map(async (entry) => await this._nestedAttributesEntryPayloadForSubmittedValue(TargetModelClass, entry))
+      )
+    }
+
+    if (value == null) return []
+    if (Array.isArray(value)) {
+      throw new Error(`${ModelClass.name}#${relationshipName}Attributes must be an object`)
+    }
+
+    return [await this._nestedAttributesEntryPayloadForSubmittedValue(TargetModelClass, value)]
+  }
+
+  /**
+   * Converts one submitted Rails-style nested attributes object into transport payload shape.
+   * @param {FrontendModelClass} ModelClass - Nested child model class.
+   * @param {?} submittedEntry - Submitted nested attributes entry.
+   * @returns {Promise<Record<string, ?>>} Transport nested-attributes entry.
+   */
+  async _nestedAttributesEntryPayloadForSubmittedValue(ModelClass, submittedEntry) {
+    if (!frontendAttachmentValueIsPlainObject(submittedEntry)) {
+      throw new Error(`${ModelClass.name} nested attributes entries must be objects`)
+    }
+
+    /** @type {Record<string, ?>} */
+    const entry = {}
+    /** @type {Record<string, ?>} */
+    const attributes = {}
+    /** @type {Record<string, ?>} */
+    const attachments = {}
+    /** @type {Record<string, Array<Record<string, ?>>>} */
+    const nestedAttributes = {}
+
+    for (const [attributeName, value] of Object.entries(submittedEntry)) {
+      if (attributeName === "id" || attributeName === "_destroy") {
+        entry[attributeName] = value
+        continue
+      }
+
+      const nestedRelationshipName = ModelClass.nestedAttributesRelationshipName(attributeName)
+
+      if (nestedRelationshipName) {
+        nestedAttributes[nestedRelationshipName] = await this._nestedAttributesPayloadForSubmittedValue(
+          ModelClass,
+          nestedRelationshipName,
+          value
+        )
+        continue
+      }
+
+      if (ModelClass.attachmentDefinition(attributeName)) {
+        attachments[attributeName] = await this._attachmentPayloadForSubmittedValue(ModelClass, attributeName, value)
+        continue
+      }
+
+      attributes[attributeName] = value
+    }
+
+    if (Object.keys(attributes).length > 0) entry.attributes = attributes
+    if (Object.keys(attachments).length > 0) entry.attachments = attachments
+    if (Object.keys(nestedAttributes).length > 0) entry.nestedAttributes = nestedAttributes
+
+    return entry
+  }
+
+  /**
+   * Normalizes a submitted attachment value for transport.
+   * @param {FrontendModelClass} ModelClass - Model class owning the attachment.
+   * @param {string} attachmentName - Attachment name.
+   * @param {?} value - Submitted attachment value.
+   * @returns {Promise<Record<string, ?> | Record<string, ?>[]>} Normalized attachment payload.
+   */
+  async _attachmentPayloadForSubmittedValue(ModelClass, attachmentName, value) {
+    const attachmentDefinition = ModelClass.attachmentDefinition(attachmentName)
+
+    if (attachmentDefinition?.type === "hasMany") {
+      const values = Array.isArray(value) ? value : [value]
+
+      return await Promise.all(values.map(async (entry) => await normalizeFrontendAttachmentInput(entry)))
+    }
+
+    if (Array.isArray(value)) {
+      const lastValue = value[value.length - 1]
+
+      if (lastValue === undefined) {
+        throw new Error(`${ModelClass.name}#${attachmentName} attachment array cannot be empty`)
+      }
+
+      return await normalizeFrontendAttachmentInput(lastValue)
+    }
+
+    return await normalizeFrontendAttachmentInput(value)
+  }
+
   /**
    * After a parent save with `nestedAttributes`, the server response includes
    * preloaded versions of the affected relationships. This replaces the local
@@ -3779,9 +3995,7 @@ export default class FrontendModelBase {
    * @returns {void}
    */
   _reconcileNestedAttributesFromResponse(response) {
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const ModelClass = frontendModelClassFor(this)
     const resourceConfig = typeof ModelClass.resourceConfig === "function" ? ModelClass.resourceConfig() : null
     const nestedAttributesConfig = resourceConfig?.nestedAttributes
 
@@ -3808,7 +4022,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs execute command.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {FrontendModelCommandType} commandType - Command type.
    * @param {Record<string, ?>} payload - Command payload.
    * @returns {Promise<Record<string, ?>>} - Parsed JSON response.
@@ -3885,7 +4099,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs execute custom command.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {object} args - Command arguments.
    * @param {string} args.commandName - Raw command path segment.
    * @param {FrontendModelRequestCommandType} args.commandType - Logical command type for error handling.
@@ -3933,7 +4147,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs throw on error frontend model response.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @param {object} args - Arguments.
    * @param {FrontendModelRequestCommandType} args.commandType - Command type.
    * @param {Record<string, ?>} args.response - Decoded response.
@@ -3992,7 +4206,7 @@ export default class FrontendModelBase {
 
   /**
    * Runs configured frontend model attribute names.
-   * @this {typeof FrontendModelBase}
+   * @this {FrontendModelClass}
    * @returns {Set<string>} - Configured frontend model attribute names.
    */
   static configuredFrontendModelAttributeNames() {