feat!: add route-based data recording with recordPageData (closes #244)

Introduces a new data recording API that organizes experiment data by route/page name and visit number, making it easier to track which data came from which part of an experiment and which visit.

New features:
  - recordPageData(data, routeName?) - records to pageData_<routeName>
    with visit_N sub-objects for multi-visit tracking
  - computeCompletionCode() - moved from ThanksView to useAPI for reuse
  - getAllPageData getter in smilestore

  Data structure per route:
      pageData_<routeName>: {
        visit_0: {
          timestamps: [ts1, ts2],  // parallel arrays
          data: [data1, data2]
        },
        visit_1: {
          timestamps: [ts3],
          data: [data3]
        }
      }

Each visit to a route creates a new visit_N object, keeping data from different visits cleanly separated.

Deprecations (still functional with warnings):
 - recordForm() - use recordPageData() instead
 - recordData() - use recordPageData() instead

BREAKING CHANGE: Completion code hash now uses pageData_* fields (falls back to studyData for backward compatibility)

- Includes docs and tests

* build: add prettier npm run command

Author: gureckis

docs/api.md

@@ -293,24 +293,65 @@ using these methods, ensure your data objects are Firestore-safe:
 Complex JavaScript objects (like functions, classes, or objects with circular
 references) must be converted to Firestore-safe formats before saving.
 
-- `recordForm(name, myFirestoreSafeObject)`: Saves form data for any arbitrarily
-  named form (see [DemographicSurvey](/coding/views#demographic-survey) for an
-  example). The object must be Firestore-safe.
+- `recordPageData(data, routeName?)`: **Recommended** - Records data organized
+  by route/page name and visit number. Data is stored in `pageData_<routeName>`
+  with separate `visit_N` objects for each time the route is visited (e.g.,
+  `visit_0`, `visit_1`, etc.). Each visit contains `timestamps` and `data`
+  arrays that grow with each call during that visit. If routeName is omitted,
+  uses the current route name. Returns `true` on success, `false` on validation
+  failure. The data must be Firestore-safe and will be validated before
+  recording:
+  - Must be an object (not an array) - arrays would create nested arrays which
+    Firestore doesn't support
+  - Cannot contain nested arrays (e.g., `[[1,2], [3,4]]`)
+  - Cannot contain functions or symbols
+  - Keys cannot contain `.`, `/`, `[`, `]`, or `*`
+
+  Example stored structure:
+
+  ```javascript
+  pageData_trial: {
+    visit_0: {  // First visit to this route
+      timestamps: [
+        1702300000000,  // [0] first recordPageData() call
+        1702300001000   // [1] second recordPageData() call
+      ],
+      data: [
+        { response: 'A', rt: 450 },  // [0] first recordPageData() call
+        { response: 'B', rt: 520 }   // [1] second recordPageData() call
+      ]
+    },
+    visit_1: {  // Second visit to this route (e.g., participant returned)
+      timestamps: [1702300100000],
+      data: [
+        { response: 'C', rt: 380 }
+      ]
+    }
+  }
+  ```
+
+  Within each visit, `timestamps[i]` corresponds to `data[i]`. Each call to
+  `recordPageData()` appends one timestamp and one data object to the current
+  visit.
+
 - `recordProperty(name, FirestoreSafeObject)`: Saves a Firestore-safe object at
   the top level of the data object. This does not save the data to the database,
   but it does record it in the local state. The next call to `saveData()` will
   save the data to the database.
-- `recordStep()`: Records the current step in the stepper. This does not save
-  the data to the database, but it does record it in the local state. The next
-  call to `saveData()` will save the data to the database.
-- `recordData(myFirestoreSafeObject)`: Records a Firestore-safe object in the
-  trials. This does not save the data to the database, but it does record it in
-  the local state. The next call to `saveData()` will save the data to the
-  database.
+- `recordStep()`: Records the current step data using `recordPageData()`. This
+  does not save the data to the database, but it does record it in the local
+  state. The next call to `saveData()` will save the data to the database.
 - `recordWindowEvent(type, event_data = null)`: Records a window event. The
   event_data must be Firestore-safe if provided.
 - `saveData(force)`: Saves the current data to the database (force save if
   specified). All data must be Firestore-safe.
+- `computeCompletionCode()`: Generates a unique completion code by hashing all
+  `pageData_*` fields (falls back to `studyData` for backward compatibility).
+
+**Deprecated methods** (still functional but will log warnings):
+
+- `recordForm(name, data)`: Use `recordPageData(data)` instead.
+- `recordData(data)`: Use `recordPageData(data)` instead.
 
 ### Data Query Methods
 

docs/coding/autofill.md

@@ -133,7 +133,7 @@ function autofill() {
 
     var t = api.faker.render(trials[step.index()])
     api.debug(t)
-    api.recordData(t)
+    api.recordPageData(t)
 
     step.next()
   }
@@ -149,7 +149,7 @@ function is steps through each trial, rendering the data for that trial, saving
 it to the smilestore database, then advancing to the next step. The rendering
 step calls the `api.faker.*()` methods as defined and makes "fake" data for the
 trial. This data is then [recorded to the database](/coding/datastorage) using
-`api.recordData()`.
+`api.recordPageData()`.
 
 ## The Autofill API
 

docs/coding/datastorage.md

@@ -204,22 +204,108 @@ Firebase/Firestore or the LocalStorage in the browser.
 
 ## Writing Data to the Global Store
 
-The preferred way to write data to the store is to use the [Smile API](/api):
+The preferred way to write data to the store is to use the [Smile API](/api).
+
+### Recording Page-Based Data (Recommended)
+
+The `recordPageData()` method organizes data by route/page name, making it easy
+to track which data came from which part of your experiment:
 
 ```vue
 <script setup>
-import SmileAPI from '@/core/composables/useAPI'
-const api = SmileAPI()
+import useAPI from '@/core/composables/useAPI'
+const api = useAPI()
+
+// Records to pageData_<current_route_name>
+api.recordPageData({
+  trialNum: 1,
+  response: 'correct',
+  rt: 543,
+})
+
+// Or specify explicit page name
+api.recordPageData({ data: 'value' }, 'custom_page')
+</script>
+```
+
+Data is automatically organized by visit, so if a participant visits the same
+page multiple times, each visit's data is tracked separately:
+
+```javascript
+// Example data structure in Firestore
+{
+  pageData_consent: [
+    {
+      visitIndex: 0,
+      timestamps: [1701619200000, 1701619205000],  // timestamps[i] corresponds to data[i]
+      data: [{ agreed: true }, { additionalInfo: "..." }]
+    }
+  ],
+  pageData_experiment: [
+    {
+      visitIndex: 0,
+      timestamps: [1701619210000, 1701619215000, 1701619220000],
+      data: [{ trial: 1, rt: 500 }, { trial: 2, rt: 450 }, { trial: 3, rt: 480 }]
+    }
+  ]
+}
+```
+
+### Deprecated Methods
+
+:::warning Deprecated The following methods are deprecated and will be removed
+in a future version. They still work but will log deprecation warnings. Please
+migrate to `recordPageData()`. :::
 
+**`recordData(data)`** - Previously used to append data to a generic `studyData`
+array:
+
+```vue
+<script setup>
+// DEPRECATED - use recordPageData() instead
 api.recordData({
-        trialnum: step_index.value,
-        word: step.value.word,
-        color: step.value.color,
-        condition: step.value.condition,
-        response: e.key,
-      })
+  trialnum: step_index.value,
+  word: step.value.word,
+  response: e.key,
+})
+</script>
 ```
 
+**`recordForm(name, data)`** - Previously used to record form submissions:
+
+```vue
+<script setup>
+// DEPRECATED - use recordPageData() instead
+api.recordForm('demographicForm', formData)
+</script>
+```
+
+### Completion Codes
+
+The `computeCompletionCode()` method generates a unique completion code based on
+the recorded data. This is useful for verifying participant completion across
+recruitment platforms:
+
+```vue
+<script setup>
+import useAPI from '@/core/composables/useAPI'
+const api = useAPI()
+
+// Generate and set completion code
+const completionCode = api.computeCompletionCode()
+api.setCompletionCode(completionCode)
+</script>
+```
+
+The completion code is a hash of all `pageData_*` fields (or `studyData` for
+backward compatibility) with a status suffix:
+
+- `oo` - participant completed the study
+- `xx` - participant withdrew
+
+This method is automatically called in the default `ThanksView.vue` component,
+but you can call it manually if needed elsewhere.
+
 The API provides several useful methods for saving data to the store (see the
 [full docs](/api)).
 

docs/styling/forms.md

@@ -105,17 +105,17 @@ experimental phase:
 
 ```javascript
 function finish() {
-  api.recordForm('feedbackForm', api.persist.forminfo)
+  api.recordPageData(api.persist.forminfo)
   api.saveData(true) // force a data save
   api.goNextView()
 }
 ```
 
-The recordForm method tags the form data with a specific identifier, making it
-easy to locate this data during analysis. The forced data save ensures that the
-form responses are immediately persisted to the backend, preventing any data
-loss. Only after the data is safely recorded does the function navigate to the
-next view in the experimental sequence.
+The `recordPageData` method automatically organizes the data by route name
+(e.g., `pageData_feedback`), making it easy to locate this data during analysis.
+The forced data save ensures that the form responses are immediately persisted
+to the backend, preventing any data loss. Only after the data is safely recorded
+does the function navigate to the next view in the experimental sequence.
 
 ### Development and Testing Support
 

package.json

@@ -42,7 +42,8 @@
     "setup_project": "sh scripts/setup_project.sh",
     "force_deploy": "sh scripts/force_deploy.sh",
     "upload_config": "sh scripts/update_config.sh",
-    "release": "bumpp package.json"
+    "release": "bumpp package.json",
+    "prettier": "npx prettier --write ."
   },
   "dependencies": {
     "@codenamize/codenamize": "1.1.1",