From 838947e06daf2ba4b550589deb05ffacf0feeed9 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Thu, 3 Sep 2026 01:48:27 +0000
Subject: [PATCH 1/5] P4: Share AddClassForm between Add Class and Onboarding
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extract flat enroll UI/logic into AddClassForm (enrollClass via
store.add_class). Thin shells keep modal/welcome chrome only.
Add parseJoinRef helper + CI unit tests for join-ref → bare classId.

Co-authored-by: Sander Vonk <sandervonk@users.noreply.github.com>
---
 .github/workflows/ci.yml               |   3 +
 package.json                           |   1 +
 scripts/test-join-class.mjs            |  82 ++++++
 src/common/joinClass.ts                |  49 ++++
 src/components/Portal/AddClassForm.vue | 355 +++++++++++++++++++++++++
 src/views/Portal/AddClass.vue          | 276 +------------------
 src/views/Portal/Onboarding.vue        | 124 +--------
 7 files changed, 511 insertions(+), 379 deletions(-)
 create mode 100644 scripts/test-join-class.mjs
 create mode 100644 src/common/joinClass.ts
 create mode 100644 src/components/Portal/AddClassForm.vue

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d8159a93..ac4d04dd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -46,5 +46,8 @@ jobs:
       - name: Repeating edit-scope tests
         run: npm run test:repeating-scope
 
+      - name: Join-class ref tests
+        run: npm run test:join-class
+
       - name: Build
         run: npm run build
diff --git a/package.json b/package.json
index 2c3d0b75..87f5bc1e 100644
--- a/package.json
+++ b/package.json
@@ -14,6 +14,7 @@
     "test:me-board": "node --experimental-strip-types scripts/test-me-board.mjs",
     "test:acting-as": "node --experimental-strip-types scripts/test-acting-as.mjs",
     "test:repeating-scope": "node --experimental-strip-types scripts/test-repeating-scope.mjs",
+    "test:join-class": "node --experimental-strip-types scripts/test-join-class.mjs",
     "deploy": "node deploy.js",
     "postbuild": "cross-env OS_TYPE=$(uname -s) npm-run-all --parallel copy-files echo-message",
     "copy-files": "npm run copy-win || npm run copy-nix",
diff --git a/scripts/test-join-class.mjs b/scripts/test-join-class.mjs
new file mode 100644
index 00000000..3cc75c77
--- /dev/null
+++ b/scripts/test-join-class.mjs
@@ -0,0 +1,82 @@
+/**
+ * Unit tests for P4 join-ref → bare classId resolution (Add Class / Onboarding).
+ * Run: node --experimental-strip-types scripts/test-join-class.mjs
+ */
+import { parseJoinRef } from "../src/common/joinClass.ts";
+
+let failed = 0;
+
+function assert(cond, msg) {
+  if (!cond) {
+    failed++;
+    console.error("FAIL:", msg);
+  } else {
+    console.log("ok:", msg);
+  }
+}
+
+function assertEq(actual, expected, label) {
+  const ok = JSON.stringify(actual) === JSON.stringify(expected);
+  if (!ok) {
+    failed++;
+    console.error(
+      `FAIL: ${label}\n  expected: ${JSON.stringify(expected)}\n  actual:   ${JSON.stringify(actual)}`
+    );
+  } else {
+    console.log(`ok: ${label}`);
+  }
+}
+
+const org = "mvla.net";
+const orgAt = "@mvla.net";
+
+console.log("--- parseJoinRef (P4 flat enroll) ---\n");
+
+assertEq(parseJoinRef(null, org), null, "null → null");
+assertEq(parseJoinRef("", org), null, "empty → null");
+assertEq(parseJoinRef("   ", org), null, "whitespace → null");
+
+assertEq(
+  parseJoinRef("abc123", org),
+  { classId: "abc123", needsTeacherLookup: true },
+  "bare classId needs teacher dual-read"
+);
+
+assertEq(
+  parseJoinRef("t@mvla.net/abc123", org),
+  { classId: "abc123", teacherEmail: "t@mvla.net", needsTeacherLookup: false },
+  "email/classId → bare classId + teacher"
+);
+
+assertEq(
+  parseJoinRef("t@mvla.net~abc123", org),
+  { classId: "abc123", teacherEmail: "t@mvla.net", needsTeacherLookup: false },
+  "email~classId → bare classId + teacher"
+);
+
+assertEq(
+  parseJoinRef("t~abc123", org),
+  { classId: "abc123", teacherEmail: "t@mvla.net", needsTeacherLookup: false },
+  "local~classId expands org domain"
+);
+
+assertEq(
+  parseJoinRef("t~abc123", orgAt),
+  { classId: "abc123", teacherEmail: "t@mvla.net", needsTeacherLookup: false },
+  "local~classId with @orgDomain store form"
+);
+
+assertEq(
+  parseJoinRef("  teacher@mvla.net/cls9  ", org),
+  { classId: "cls9", teacherEmail: "teacher@mvla.net", needsTeacherLookup: false },
+  "trims whitespace around join ref"
+);
+
+assert(parseJoinRef("only-id", org)?.needsTeacherLookup === true, "short ref flags lookup");
+assert(parseJoinRef("a@b.c/id", org)?.needsTeacherLookup === false, "prefixed ref skips lookup");
+
+if (failed) {
+  console.error(`\n${failed} failure(s)`);
+  process.exit(1);
+}
+console.log("\nall join-class tests passed");
diff --git a/src/common/joinClass.ts b/src/common/joinClass.ts
new file mode 100644
index 00000000..9eb35d9b
--- /dev/null
+++ b/src/common/joinClass.ts
@@ -0,0 +1,49 @@
+/**
+ * P4 flat enroll helpers for Add Class / Onboarding join-ref resolution.
+ * Prefer bare classId enrollment pointers; dual-read still resolves legacy
+ * email/classId and local~classId forms during soak.
+ *
+ * @module common/joinClass
+ */
+
+import { parseClassId } from "./paths";
+
+export interface JoinRefParts {
+  /** Bare classId for enrollClass({ classId }) / store.add_class. */
+  classId: string;
+  /** Present when the join ref included a teacher email or local prefix. */
+  teacherEmail?: string;
+  /**
+   * True for short bare classId refs — caller must dual-read (class_from_ref)
+   * to obtain teacher email before listing classes.
+   */
+  needsTeacherLookup: boolean;
+}
+
+/**
+ * Parse a join ref (from route or code→ref lookup) into teacher + bare classId.
+ * Does not touch Firestore; async teacher lookup stays in the Vue form.
+ *
+ * Accepts: classId | email/classId | local~classId (slash or ~).
+ */
+export function parseJoinRef(
+  ref: string | undefined | null,
+  orgDomain: string
+): JoinRefParts | null {
+  if (!ref || typeof ref !== "string") return null;
+  const trimmed = ref.trim();
+  if (!trimmed) return null;
+
+  const parsed = parseClassId(trimmed, orgDomain);
+  if (!parsed?.classId) return null;
+
+  if (!parsed.hasTeacherPrefix) {
+    return { classId: parsed.classId, needsTeacherLookup: true };
+  }
+
+  return {
+    classId: parsed.classId,
+    teacherEmail: parsed.teacherEmail,
+    needsTeacherLookup: false,
+  };
+}
diff --git a/src/components/Portal/AddClassForm.vue b/src/components/Portal/AddClassForm.vue
new file mode 100644
index 00000000..137ff6b0
--- /dev/null
+++ b/src/components/Portal/AddClassForm.vue
@@ -0,0 +1,355 @@
+<template>
+  <div class="add-class-form">
+    <div class="overlay_contents" ref="contents">
+      <div class="overlay_contents_text">
+        <template v-if="variant === 'welcome'">
+          {{ welcomeName }}Let's get you set up with your first class
+        </template>
+        <template v-else-if="is_join">
+          <span
+            >{{ $store.loaded_email == teacher_email ? "Loaded" : "Loading" }} from your teacher's
+            class {{ code ? "code" : "ref" }}</span
+          >
+        </template>
+        <template v-else>
+          <span
+            >Join a class with your teacher's details or
+            <span
+              class="click-action button_pointer_text"
+              @click="$router.push({ name: 'codeenterclass', query: $route.query })"
+              >enter a class code</span
+            >
+          </span>
+        </template>
+      </div>
+      <div class="inputs_row" v-if="!is_join">
+        <input
+          v-model="teacher_email"
+          ref="teacher_email"
+          class="styled_input"
+          type="text"
+          placeholder="Teacher's Email"
+          enterkeyhint="next"
+          @keydown.enter="$refs.class_id.focus()"
+        />
+        <select
+          ref="class_id"
+          v-model="class_id"
+          class="styled_input"
+          :disabled="!classes || !classes.length"
+          :class="{ loading_bg: loading && teacher_email }"
+        >
+          <option
+            v-for="class_obj in classes"
+            :value="class_obj.id"
+            :key="class_obj.id"
+            :disabled="class_obj.is_joined && !adding"
+          >
+            <span v-if="class_obj.is_joined && !adding">[JOINED]</span>
+            {{ $store.class_text(class_obj) }}
+          </option>
+          <option v-if="teacher_email && !classes" value="" disabled hidden selected>
+            {{ loading ? "Loading..." : "No classes found" }}
+          </option>
+          <option v-else value="" disabled hidden selected>
+            {{
+              teacher_email &&
+              classes &&
+              classes.length &&
+              teacher_email.endsWith($env.VUE_APP_ORG_DOMAIN)
+                ? "Select a Class"
+                : ""
+            }}
+          </option>
+        </select>
+      </div>
+      <div class="inputs_row" v-else>
+        <div
+          id="code_ref"
+          class="styled_input"
+          :class="{ code: code, ref: $route.params.ref }"
+          type="text"
+          placeholder="Join Code / Reference"
+          enterkeyhint="send"
+          @keydown.enter="add_class"
+        >
+          {{ code || $route.params.ref || "" }}
+        </div>
+      </div>
+      <div class="overlay_contents_text" v-if="class_obj && variant !== 'welcome'">
+        {{
+          class_obj && class_obj.is_joined && !adding
+            ? "You've already joined"
+            : "You'll be joining"
+        }}
+        <a
+          class="class_name button_pointer_text"
+          :href="`/view/${cleaned_ref}`"
+          @click="
+            $event.preventDefault();
+            $router.push({ name: 'viewclass', params: { ref: cleaned_ref }, query: $route.query });
+          "
+          :style="{
+            '--color-class': class_obj.color,
+            '--color-class-alt': class_obj.color + '2d',
+          }"
+          >{{ $store.class_text(class_obj) }}</a
+        >
+      </div>
+      <div v-if="class_obj && variant !== 'welcome'" class="overlay_contents_text">
+        <br />
+      </div>
+      <div class="overlay_contents_text">
+        <template v-if="variant === 'welcome'">
+          You can add more classes later from the
+          <span class="button_pointer_text">Join a Class</span> button on the left sidebar
+        </template>
+        <template v-else-if="is_join">
+          <span
+            >If you're having trouble, ask your teacher to share their class code again using the
+            <span class="button_pointer_text">Share</span> button on the class edit page
+          </span>
+        </template>
+        <template v-else>
+          <span>Enter your teacher's email above to see their classes</span>
+        </template>
+      </div>
+    </div>
+    <div class="bottom_actions">
+      <button
+        :class="[dismissClass, 'click_escape']"
+        @click="$emit('close')"
+      >
+        {{ dismissLabel }}
+      </button>
+      <div class="flex_spacer"></div>
+      <button
+        class="continue_action"
+        :class="[
+          variant === 'welcome' ? 'click_ctrlenter' : '',
+          {
+            loading_bg: adding || (is_join && loading),
+            alt_bg: !canSubmit,
+          },
+        ]"
+        @click="add_class"
+        :disabled="!canSubmit"
+      >
+        Add Class
+      </button>
+    </div>
+  </div>
+</template>
+
+<script>
+/**
+ * Shared Add Class / Onboarding enroll form (P4).
+ *
+ * Owns teacher email + class picker (or join-code display), loading / already-joined
+ * state, and submit → store.add_class → enrollClass({ classId }). Flat enroll only —
+ * no nested classes/{email}/classes writers.
+ *
+ * Shells (AddClass.vue, Onboarding.vue) supply modal chrome / welcome framing.
+ *
+ * @module AddClassForm
+ * @see mvtt-server#32 flat planner writers
+ */
+import { ErrorToast, WarningToast } from "@svonk/util";
+import smoothReflow from "vue-smooth-reflow";
+import { parseJoinRef } from "@/common/joinClass";
+
+export default {
+  name: "AddClassForm",
+  emits: ["close"],
+  mixins: [smoothReflow],
+  props: {
+    /**
+     * `add` — full Add Class / join-code modal body.
+     * `welcome` — Onboarding framing (same enroll semantics; no join-route UI).
+     */
+    variant: {
+      type: String,
+      default: "add",
+      validator: (v) => v === "add" || v === "welcome",
+    },
+    dismissLabel: {
+      type: String,
+      default: "Close",
+    },
+    dismissClass: {
+      type: String,
+      default: "close_action",
+    },
+  },
+  data() {
+    return {
+      teacher_email: "",
+      class_id: "",
+      adding: false,
+    };
+  },
+  mounted() {
+    this.$smoothReflow({
+      el: this.$refs.contents,
+      childTransitions: true,
+    });
+    if (this.$refs.teacher_email) {
+      this.$refs.teacher_email.focus();
+    }
+    // Join-code / ref routes only apply to the add variant
+    if (this.variant === "add") {
+      this.use_ref();
+    }
+    if (
+      !this.is_join &&
+      this.$store.loaded_email &&
+      this.$store.get_loaded_classes.some((class_obj) => !class_obj.is_joined)
+    ) {
+      this.teacher_email = this.$store.loaded_email;
+    }
+  },
+  computed: {
+    class_obj() {
+      if (!this.classes) return false;
+      return this.classes.find((class_obj) => class_obj.id === this.class_id) || false;
+    },
+    cleaned_ref() {
+      return this.$store.path_to_ref(this.teacher_email, this.class_id);
+    },
+    loading() {
+      return this.$store.loaded_email !== this.teacher_email;
+    },
+    classes() {
+      if (!this.teacher_email) {
+        return null;
+      } else if (this.teacher_email === this.$store.loaded_email) {
+        return this.$store.get_loaded_classes;
+      }
+      this.$store.fetch_classes_by_email(this.teacher_email);
+      return null;
+    },
+    is_join() {
+      if (this.variant !== "add") return false;
+      return this.$route?.name == "refclass" || this.$route?.name == "codeclass";
+    },
+    code() {
+      return this.$route?.params?.code && this.$route.params?.code.toLowerCase();
+    },
+    welcomeName() {
+      if (this.$store.user && this.$store.user.displayName)
+        return "Hi " + this.$store.user.displayName.split(" ")[0] + ", ";
+      return "";
+    },
+    canSubmit() {
+      if (!this.teacher_email || !this.class_id) return false;
+      if (this.class_obj && this.class_obj.is_joined && !this.adding) return false;
+      return true;
+    },
+  },
+  methods: {
+    /**
+     * Enroll via store.add_class → enrollClass({ classId }) (bare classId preferred).
+     * P4: no nested classes/{email}/classes writes from this path.
+     */
+    async add_class() {
+      if (!this.canSubmit && !this.adding) return;
+      this.adding = true;
+      this.$store
+        .add_class(this.teacher_email, this.class_id, this.class_obj.name, this.class_obj.period)
+        .then(() => {
+          this.$emit("close");
+          return Promise.resolve();
+        })
+        .catch(() => {
+          this.adding = false;
+          return Promise.reject();
+        });
+    },
+    async use_ref() {
+      let ref = this.$route.params?.ref;
+      if (!ref && this.code) {
+        try {
+          ref = await this.$store.ref_from_code(this.code);
+        } catch (err) {
+          new ErrorToast("Invalid join code", err, 4000);
+          this.$status.log("🔥 " + err);
+          if (this.$route?.query?.manual) {
+            this.$router.push({ name: "codeenterclass", query: this.$route.query });
+          } else {
+            this.to_normal_add();
+          }
+          return;
+        }
+      }
+
+      if (ref && this.is_join) {
+        this.$status.log("🔍 Attempting to use class join ref", ref);
+        // P4: parseJoinRef → bare classId (+ teacher when prefixed); dual-read for short ids
+        const parts = parseJoinRef(ref, this.$store.ORG_DOMAIN);
+        if (!parts?.classId) {
+          new WarningToast("Couldn't find that class", 3000);
+          this.$status.log("🔥 Unparseable join ref", ref);
+          this.to_normal_add();
+          return;
+        }
+
+        let _email = parts.teacherEmail;
+        const _id = parts.classId;
+
+        if (parts.needsTeacherLookup) {
+          try {
+            const class_obj = await this.$store.class_from_ref(_id);
+            _email = class_obj._teacher_email;
+            if (!_email) throw "No teacher email on class";
+          } catch (err) {
+            new WarningToast("Couldn't find that class", 3000);
+            this.$status.log("🔥 Unfound class for short join ref", ref, err);
+            this.to_normal_add();
+            return;
+          }
+        }
+
+        this.teacher_email = _email;
+        this.$store.fetch_classes_by_email(_email);
+        while (this.$store.loaded_email !== this.teacher_email) {
+          await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+
+        let found = this.$store?.get_loaded_classes?.find((class_obj) => class_obj.id === _id);
+        if (found) {
+          this.class_id = _id;
+          if (found.is_joined) {
+            new WarningToast("You've already joined this class", 3000);
+            this.$status.log("🔥 Already joined class", ref);
+          }
+        } else {
+          new WarningToast("Couldn't find that class", 3000);
+          this.$status.log("🔥 Unfound class for join ref", ref);
+          this.to_normal_add();
+        }
+      } else if (this.is_join) {
+        new WarningToast("Please provide a join code", 3000);
+        this.to_normal_add();
+      }
+    },
+    to_normal_add() {
+      this.$router.push({ name: "addclass", query: this.$route.query });
+    },
+  },
+};
+</script>
+
+<style>
+#code_ref {
+  text-align: center;
+  font-weight: 600;
+  height: auto;
+  padding: var(--padding-overlay-input);
+}
+#code_ref.code {
+  font-size: 4em;
+}
+#code_ref.ref {
+  font-size: 1.25em;
+}
+</style>
diff --git a/src/views/Portal/AddClass.vue b/src/views/Portal/AddClass.vue
index 954a48ed..4dbb5565 100644
--- a/src/views/Portal/AddClass.vue
+++ b/src/views/Portal/AddClass.vue
@@ -3,289 +3,31 @@
     <header class="modal_header">
       <h2 class="header_style modal_header_title">{{ !is_join ? "Add a" : "Join" }} Class</h2>
     </header>
-    <div class="overlay_contents" ref="contents">
-      <div class="overlay_contents_text">
-        <span v-if="is_join"
-          >{{ $store.loaded_email == teacher_email ? "Loaded" : "Loading" }} from your teacher's
-          class {{ code ? "code" : "ref" }}</span
-        >
-        <span v-else
-          >Join a class with your teacher's details or
-          <span
-            class="click-action button_pointer_text"
-            @click="$router.push({ name: 'codeenterclass', query: $route.query })"
-            >enter a class code</span
-          >
-        </span>
-      </div>
-      <div class="inputs_row" v-if="!is_join">
-        <input
-          v-model="teacher_email"
-          ref="teacher_email"
-          class="styled_input"
-          type="text"
-          placeholder="Teacher's Email"
-          enterkeyhint="next"
-          @keydown.enter="$refs.class_id.focus()"
-        />
-        <select
-          ref="class_id"
-          v-model="class_id"
-          class="styled_input"
-          :disabled="!classes || !classes.length"
-          :class="{ loading_bg: loading && teacher_email }"
-        >
-          <option
-            v-for="class_obj in classes"
-            :value="class_obj.id"
-            :key="class_obj.id"
-            :disabled="class_obj.is_joined && !adding"
-          >
-            <span v-if="class_obj.is_joined && !adding">[JOINED]</span>
-            {{ $store.class_text(class_obj) }}
-          </option>
-          <option v-if="teacher_email && !classes" value="" disabled hidden selected>
-            {{ loading ? "Loading..." : "No classes found" }}
-          </option>
-          <option v-else value="" disabled hidden selected>
-            {{
-              teacher_email &&
-              classes &&
-              classes.length &&
-              teacher_email.endsWith($env.VUE_APP_ORG_DOMAIN)
-                ? "Select a Class"
-                : ""
-            }}
-          </option>
-        </select>
-      </div>
-      <div class="inputs_row" v-else>
-        <div
-          id="code_ref"
-          class="styled_input"
-          :class="{ code: code, ref: $route.params.ref }"
-          type="text"
-          placeholder="Join Code / Reference"
-          enterkeyhint="send"
-          @keydown.enter="add_class"
-        >
-          {{ code || $route.params.ref || "" }}
-        </div>
-      </div>
-      <div class="overlay_contents_text" v-if="class_obj">
-        {{
-          class_obj && class_obj.is_joined && !adding
-            ? "You've already joined"
-            : "You'll be joining"
-        }}
-        <a
-          class="class_name button_pointer_text"
-          :href="`/view/${cleaned_ref}`"
-          @click="
-            $event.preventDefault();
-            $router.push({ name: 'viewclass', params: { ref: cleaned_ref }, query: $route.query });
-          "
-          :style="{
-            '--color-class': class_obj.color,
-            '--color-class-alt': class_obj.color + '2d',
-          }"
-          >{{ $store.class_text(class_obj) }}</a
-        >
-      </div>
-      <div v-if="class_obj" class="overlay_contents_text">
-        <br />
-      </div>
-      <div class="overlay_contents_text">
-        <span v-if="is_join"
-          >If you're having trouble, ask your teacher to share their class code again using the
-          <span class="button_pointer_text">Share</span> button on the class edit page
-        </span>
-        <span v-else>Enter your teacher's email above to see their classes</span>
-      </div>
-    </div>
-    <div class="bottom_actions">
-      <button class="close_action click_escape" @click="$emit('close')">Close</button>
-      <div class="flex_spacer"></div>
-      <button
-        class="continue_action"
-        @click="add_class"
-        :disabled="!teacher_email || !class_id || (class_obj && class_obj.is_joined && !adding)"
-        :class="{
-          loading_bg: adding || (is_join && loading),
-          alt_bg: !teacher_email || !class_id || (class_obj && class_obj.is_joined && !adding),
-        }"
-      >
-        Add Class
-      </button>
-    </div>
+    <!-- P4: shared enroll form → store.add_class / enrollClass({ classId }); flat only -->
+    <AddClassForm variant="add" dismiss-label="Close" @close="$emit('close')" />
   </main>
 </template>
 
 <script>
 /**
- * Component for adding a class to the user's dashboard / ClassList.
+ * Thin shell for Add Class modal chrome.
+ * Enroll UI/logic lives in AddClassForm (shared with Onboarding).
  *
  * @module AddClassView
- * @description Modal that allows the user to add a class to their dashboard.
- * @requires module:store/MainStore
- * @emits {Function} close - An event emitted when the class is added or the modal is closed.
+ * @emits {Function} close
  */
-import { ErrorToast, WarningToast /*SuccessToast*/ } from "@svonk/util";
-import smoothReflow from "vue-smooth-reflow";
+import AddClassForm from "@/components/Portal/AddClassForm.vue";
+
 export default {
   name: "AddClassView",
+  components: { AddClassForm },
   emits: ["close"],
-  mixins: [smoothReflow],
-  data() {
-    return {
-      teacher_email: "",
-      class_id: "",
-      adding: false,
-    };
-  },
-  mounted() {
-    this.$smoothReflow({
-      el: this.$refs.contents,
-      childTransitions: true,
-    });
-    if (this.$refs.teacher_email) {
-      this.$refs.teacher_email.focus();
-    }
-    // if ref is provided, set email and class_id
-    this.use_ref();
-    if (
-      !this.is_join &&
-      this.$store.loaded_email &&
-      this.$store.get_loaded_classes.some((class_obj) => !class_obj.is_joined)
-    ) {
-      this.teacher_email = this.$store.loaded_email;
-    }
-  },
   computed: {
-    class_obj() {
-      if (!this.classes) return false;
-      return this.classes.find((class_obj) => class_obj.id === this.class_id) || false;
-    },
-    cleaned_ref() {
-      return this.$store.path_to_ref(this.teacher_email, this.class_id);
-    },
-    loading() {
-      return this.$store.loaded_email !== this.teacher_email;
-    },
-    classes() {
-      if (!this.teacher_email) {
-        return null;
-      } else if (this.teacher_email === this.$store.loaded_email) {
-        return this.$store.get_loaded_classes;
-      }
-      // commit store fetch_classes_by_email with teacher_email
-      this.$store.fetch_classes_by_email(this.teacher_email);
-
-      return null;
-    },
     is_join() {
       return this.$route?.name == "refclass" || this.$route?.name == "codeclass";
     },
-    code() {
-      return this.$route?.params?.code && this.$route.params?.code.toLowerCase();
-    },
-  },
-  methods: {
-    async add_class() {
-      this.adding = true;
-      this.$store
-        .add_class(this.teacher_email, this.class_id, this.class_obj.name, this.class_obj.period)
-        .then(() => {
-          this.$emit("close");
-          return Promise.resolve();
-        })
-        .catch(() => {
-          this.adding = false;
-          return Promise.reject();
-        });
-    },
-    async use_ref() {
-      let ref = this.$route.params?.ref;
-      if (!ref && this.code) {
-        try {
-          ref = await this.$store.ref_from_code(this.code);
-        } catch (err) {
-          new ErrorToast("Invalid join code", err, 4000);
-          this.$status.log("🔥 " + err);
-          if (this.$route?.query?.manual) {
-            this.$router.push({ name: "codeenterclass", query: this.$route.query });
-          } else {
-            this.to_normal_add();
-          }
-          return;
-        }
-      }
-
-      if (ref && this.is_join) {
-        this.$status.log("🔍 Attempting to use class join ref", ref);
-        const parts = String(ref).split(/[~/]/).filter(Boolean);
-        let _email;
-        let _id;
-        if (parts.length === 1) {
-          // Short classId — resolve teacher via dual-read
-          _id = parts[0];
-          try {
-            const class_obj = await this.$store.class_from_ref(_id);
-            _email = class_obj._teacher_email;
-            if (!_email) throw "No teacher email on class";
-          } catch (err) {
-            new WarningToast("Couldn't find that class", 3000);
-            this.$status.log("🔥 Unfound class for short join ref", ref, err);
-            this.to_normal_add();
-            return;
-          }
-        } else {
-          _email = parts[0];
-          _id = parts[1];
-          if (!_email.includes("@")) _email += this.$store.ORG_DOMAIN;
-        }
-        this.teacher_email = _email;
-        this.$store.fetch_classes_by_email(_email);
-        while (this.$store.loaded_email !== this.teacher_email) {
-          await new Promise((resolve) => setTimeout(resolve, 100));
-        }
-
-        let found = this.$store?.get_loaded_classes?.find((class_obj) => class_obj.id === _id);
-        if (found) {
-          this.class_id = _id;
-          if (found.is_joined) {
-            new WarningToast("You've already joined this class", 3000);
-            this.$status.log("🔥 Already joined class", ref);
-            //this.$emit("close");
-          }
-        } else {
-          new WarningToast("Couldn't find that class", 3000);
-          this.$status.log("🔥 Unfound class for join ref", ref);
-          this.to_normal_add();
-        }
-      } else if (this.is_join) {
-        new WarningToast("Please provide a join code", 3000);
-        this.to_normal_add();
-      }
-    },
-    to_normal_add() {
-      this.$router.push({ name: "addclass", query: this.$route.query });
-    },
   },
 };
 </script>
 
-<style>
-#code_ref {
-  text-align: center;
-  font-weight: 600;
-  height: auto;
-  padding: var(--padding-overlay-input);
-}
-#code_ref.code {
-  font-size: 4em;
-}
-#code_ref.ref {
-  font-size: 1.25em;
-}
-</style>
+<style></style>
diff --git a/src/views/Portal/Onboarding.vue b/src/views/Portal/Onboarding.vue
index faf8223d..767d52d5 100644
--- a/src/views/Portal/Onboarding.vue
+++ b/src/views/Portal/Onboarding.vue
@@ -3,130 +3,30 @@
     <header class="modal_header">
       <h2 class="header_style modal_header_title">Welcome to MVTime</h2>
     </header>
-    <div class="overlay_contents">
-      <div class="overlay_contents_text">{{ name }} Let's get you set up with your first class</div>
-      <div class="inputs_row">
-        <input
-          v-model="teacher_email"
-          ref="teacher_email"
-          class="styled_input"
-          type="text"
-          placeholder="Teacher's Email"
-          enterkeyhint="next"
-          @keydown.enter="$refs.class_id.focus()"
-        />
-        <select
-          ref="class_id"
-          v-model="class_id"
-          class="styled_input"
-          :disabled="!classes || !classes.length"
-          :class="{ loading_bg: loading && teacher_email }"
-        >
-          <option
-            v-for="class_obj in classes"
-            :value="class_obj.id"
-            :key="class_obj.id"
-            :disabled="class_obj.is_joined && !adding"
-          >
-            <span v-if="class_obj.is_joined && !adding">[JOINED]</span>
-            {{ $store.class_text(class_obj) }}
-          </option>
-          <option v-if="teacher_email && !classes" value="" disabled hidden selected>
-            {{ loading ? "Loading..." : "No classes found" }}
-          </option>
-          <option v-else value="" disabled hidden selected>
-            {{
-              teacher_email &&
-              classes &&
-              classes.length &&
-              teacher_email.endsWith($env.VUE_APP_ORG_DOMAIN)
-                ? "Select a Class"
-                : ""
-            }}
-          </option>
-        </select>
-      </div>
-      <div class="overlay_contents_text">
-        You can add more classes later from the
-        <span class="button_pointer_text">Join a Class</span> button on the left sidebar
-      </div>
-    </div>
-    <div class="bottom_actions">
-      <button class="back_action click_escape" @click="$emit('close')">Skip</button>
-      <div class="flex_spacer"></div>
-      <button
-        class="continue_action click_ctrlenter"
-        @click="add_class"
-        :disabled="!teacher_email || !class_id"
-      >
-        Add Class
-      </button>
-    </div>
+    <!-- P4: same AddClassForm enroll path as Add Class (welcome framing only) -->
+    <AddClassForm
+      variant="welcome"
+      dismiss-label="Skip"
+      dismiss-class="back_action"
+      @close="$emit('close')"
+    />
   </div>
 </template>
 
 <script>
 /**
- * Version of the AddClassView that is shown to new users.
+ * Welcome / Onboarding shell — thin framing around shared AddClassForm.
+ * Same create/enroll semantics as Add Class (store.add_class → enrollClass).
  *
  * @module OnboardingView
- * @description Modal that allows the user to add a class to their dashboard, with some extra intro text.
- * @requires module:store/MainStore
- * @emits {Function} close - An event emitted when the class is added or the modal is closed.
+ * @emits {Function} close
  */
+import AddClassForm from "@/components/Portal/AddClassForm.vue";
 
 export default {
   name: "OnboardingView",
+  components: { AddClassForm },
   emits: ["close"],
-  data() {
-    return {
-      teacher_email: "",
-      class_id: "",
-      adding: false,
-    };
-  },
-  computed: {
-    class_obj() {
-      if (!this.classes) return null;
-      return this.classes.find((class_obj) => class_obj.id === this.class_id) || {};
-    },
-    loading() {
-      return this.$store.loaded_email !== this.teacher_email;
-    },
-    classes() {
-      if (!this.teacher_email) {
-        return null;
-      } else if (this.teacher_email === this.$store.loaded_email) {
-        return this.$store.get_loaded_classes;
-      }
-      // commit store fetch_classes_by_email with teacher_email
-      this.$store.fetch_classes_by_email(this.teacher_email);
-
-      return null;
-    },
-    name() {
-      if (this.$store.user && this.$store.user.displayName)
-        return "Hi " + this.$store.user.displayName.split(" ")[0] + ", ";
-      return "";
-    },
-  },
-  mounted() {
-    // focus
-    this.$refs.teacher_email.focus();
-  },
-  methods: {
-    add_class() {
-      this.adding = true;
-      this.$store
-        .add_class(this.teacher_email, this.class_id, this.class_obj.name, this.class_obj.period)
-        .then(() => {
-          this.$emit("close");
-        })
-        .catch(() => {
-          this.adding = false;
-        });
-    },
-  },
 };
 </script>
 

From 98a6c3c5e5630712bf72f5dd60ff02aaf196eba2 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Thu, 3 Sep 2026 01:49:54 +0000
Subject: [PATCH 2/5] Fix parseJoinRef: colocate in paths.ts for Node tests

Relative TS imports break under --experimental-strip-types;
keep join-ref helper in the existing leaf paths module.

Co-authored-by: Sander Vonk <sandervonk@users.noreply.github.com>
---
 .env                                   | 62 ++++++++++++++++++++++++++
 scripts/test-join-class.mjs            |  2 +-
 src/common/joinClass.ts                | 49 --------------------
 src/common/paths.ts                    | 44 ++++++++++++++++++
 src/components/Portal/AddClassForm.vue |  2 +-
 5 files changed, 108 insertions(+), 51 deletions(-)
 create mode 100644 .env
 delete mode 100644 src/common/joinClass.ts

diff --git a/.env b/.env
new file mode 100644
index 00000000..07363569
--- /dev/null
+++ b/.env
@@ -0,0 +1,62 @@
+# the main brand name shown in files
+VUE_APP_BRAND_NAME_LONG=Task Tracker [BETA]
+# the short name used in the app
+VUE_APP_BRAND_NAME_SHORT=[BETA]
+# the main brand URL (without trailing slash)
+VUE_APP_BRAND_URL=http://localhost:8080
+# the main brand homepage used for pwa, etc (without trailing slash) 
+VUE_APP_BRAND_HOMEPAGE=http://localhost:8080
+# the main brand domain (without subdomain)
+VUE_APP_BRAND_DOMAIN=localhost:8080
+# excluding the hash due to limitations in the .env file
+VUE_APP_THEME_COLOR=f5c14b
+VUE_APP_THEME_ACCENT_COLOR=000000
+VUE_APP_THEME_ACCENT_COLOR_ALT=4c4c4c
+# the URL to download the sidebar
+VUE_APP_SIDEBAR_DOWNLOAD_URL=/download/mvtt-sidebar.zip
+
+# the domain for the API
+VUE_APP_BRAND_DOMAIN__API=api.mvtt.app
+# the domain that redirects to the class add view
+VUE_APP_BRAND_DOMAIN__ADDCLASS=localhost:8080/add
+# the domain that redirects to the class view
+VUE_APP_BRAND_DOMAIN__VIEWCLASS=localhost:8080/view
+# the domain that redirects to the task view
+VUE_APP_BRAND_DOMAIN__VIEWTASK=localhost:8080/view
+# the main mail address for the brand (used to send the invite mail)
+VUE_APP_BRAND_MAIL_ADDRESS=mail@mvtt.app
+
+# allowed domain hosts w/o outlink protection (either literal or *.domain.tld for wildcard)
+VUE_APP_BRAND_ALLOWED_HOSTS=mvla.net,*.mvla.net
+
+# console colors
+VUE_APP_THEME_CONSOLE_COLOR_BG=272727
+VUE_APP_THEME_CONSOLE_COLOR_TEXT=C9B092
+
+# the organization domain for user emails
+VUE_APP_ORG_DOMAIN=mvla.net
+# the organization (short) name
+VUE_APP_ORG_NAME=SCHOOL
+# links to relevant sites to be included in the basenav
+VUE_APP_ORG_LINKS=[["Docs", "https://localhost:8080/docs"]]
+# grade levels and their names
+VUE_APP_ORG_GRADES=[["student", "Student"]]
+# name for teacher acc
+VUE_APP_ORG_TEACHER_GRADE=Teacher
+
+# the API key for the Firebase project
+FIREBASE_apiKey=AIzaSyDGqqhApln4pxm4EynPCSkfwyK8aopjfCk
+# the domain for the Firebase auth
+FIREBASE_authDomain=auth.mvtt.app
+# the project ID of the Firebase project
+FIREBASE_projectId=mvtrack
+# the storage bucket for the Firebase project
+FIREBASE_storageBucket=mvtrack.appspot.com
+# the messaging sender ID for the Firebase project
+FIREBASE_messagingSenderId=1070634963357
+# the app ID for the Firebase project
+FIREBASE_appId=1:1070634963357:web:2a4abc725fff24a5199f74
+# the measurement ID for the Firebase project
+FIREBASE_measurementId=G-6LNX1KCR8E
+# the server region for the Firebase project
+FIREBASE_serverRegion=us-central1
\ No newline at end of file
diff --git a/scripts/test-join-class.mjs b/scripts/test-join-class.mjs
index 3cc75c77..77e0ebdc 100644
--- a/scripts/test-join-class.mjs
+++ b/scripts/test-join-class.mjs
@@ -2,7 +2,7 @@
  * Unit tests for P4 join-ref → bare classId resolution (Add Class / Onboarding).
  * Run: node --experimental-strip-types scripts/test-join-class.mjs
  */
-import { parseJoinRef } from "../src/common/joinClass.ts";
+import { parseJoinRef } from "../src/common/paths.ts";
 
 let failed = 0;
 
diff --git a/src/common/joinClass.ts b/src/common/joinClass.ts
deleted file mode 100644
index 9eb35d9b..00000000
--- a/src/common/joinClass.ts
+++ /dev/null
@@ -1,49 +0,0 @@
-/**
- * P4 flat enroll helpers for Add Class / Onboarding join-ref resolution.
- * Prefer bare classId enrollment pointers; dual-read still resolves legacy
- * email/classId and local~classId forms during soak.
- *
- * @module common/joinClass
- */
-
-import { parseClassId } from "./paths";
-
-export interface JoinRefParts {
-  /** Bare classId for enrollClass({ classId }) / store.add_class. */
-  classId: string;
-  /** Present when the join ref included a teacher email or local prefix. */
-  teacherEmail?: string;
-  /**
-   * True for short bare classId refs — caller must dual-read (class_from_ref)
-   * to obtain teacher email before listing classes.
-   */
-  needsTeacherLookup: boolean;
-}
-
-/**
- * Parse a join ref (from route or code→ref lookup) into teacher + bare classId.
- * Does not touch Firestore; async teacher lookup stays in the Vue form.
- *
- * Accepts: classId | email/classId | local~classId (slash or ~).
- */
-export function parseJoinRef(
-  ref: string | undefined | null,
-  orgDomain: string
-): JoinRefParts | null {
-  if (!ref || typeof ref !== "string") return null;
-  const trimmed = ref.trim();
-  if (!trimmed) return null;
-
-  const parsed = parseClassId(trimmed, orgDomain);
-  if (!parsed?.classId) return null;
-
-  if (!parsed.hasTeacherPrefix) {
-    return { classId: parsed.classId, needsTeacherLookup: true };
-  }
-
-  return {
-    classId: parsed.classId,
-    teacherEmail: parsed.teacherEmail,
-    needsTeacherLookup: false,
-  };
-}
diff --git a/src/common/paths.ts b/src/common/paths.ts
index d8c73798..f6764244 100644
--- a/src/common/paths.ts
+++ b/src/common/paths.ts
@@ -22,6 +22,22 @@ export interface ParsedClassPath {
   hasTeacherPrefix: boolean;
 }
 
+/**
+ * P4 flat enroll: join-ref parts for Add Class / Onboarding.
+ * Prefer bare classId for enrollClass; dual-read when teacher is unknown.
+ */
+export interface JoinRefParts {
+  /** Bare classId for enrollClass({ classId }) / store.add_class. */
+  classId: string;
+  /** Present when the join ref included a teacher email or local prefix. */
+  teacherEmail?: string;
+  /**
+   * True for short bare classId refs — caller must dual-read (class_from_ref)
+   * to obtain teacher email before listing classes.
+   */
+  needsTeacherLookup: boolean;
+}
+
 export interface ParsedTaskPath {
   teacherEmail?: string;
   classId: string;
@@ -86,6 +102,34 @@ export function parseClassId(
   return null;
 }
 
+/**
+ * P4: Parse a join ref (route or code→ref) into teacher + bare classId.
+ * Does not touch Firestore; async teacher lookup stays in AddClassForm.
+ * Accepts: classId | email/classId | local~classId (slash or ~).
+ * No nested classes/{email}/classes writers — bare classId enroll only.
+ */
+export function parseJoinRef(
+  ref: string | undefined | null,
+  orgDomain: string
+): JoinRefParts | null {
+  if (!ref || typeof ref !== "string") return null;
+  const trimmed = ref.trim();
+  if (!trimmed) return null;
+
+  const parsed = parseClassId(trimmed, orgDomain);
+  if (!parsed?.classId) return null;
+
+  if (!parsed.hasTeacherPrefix) {
+    return { classId: parsed.classId, needsTeacherLookup: true };
+  }
+
+  return {
+    classId: parsed.classId,
+    teacherEmail: parsed.teacherEmail,
+    needsTeacherLookup: false,
+  };
+}
+
 /**
  * Parse task identity from slash id or ~ ref.
  * Accepts: classId/taskId | email/classId/taskId | local~classId~taskId | classId~taskId
diff --git a/src/components/Portal/AddClassForm.vue b/src/components/Portal/AddClassForm.vue
index 137ff6b0..e7ba0c73 100644
--- a/src/components/Portal/AddClassForm.vue
+++ b/src/components/Portal/AddClassForm.vue
@@ -156,7 +156,7 @@
  */
 import { ErrorToast, WarningToast } from "@svonk/util";
 import smoothReflow from "vue-smooth-reflow";
-import { parseJoinRef } from "@/common/joinClass";
+import { parseJoinRef } from "@/common/paths";
 
 export default {
   name: "AddClassForm",

From 46bb14ac199369a0eb487b1855408d60ae844c71 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Thu, 3 Sep 2026 01:50:06 +0000
Subject: [PATCH 3/5] Stop tracking accidental .env; ignore local .env copies
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI already copies .env.test → .env; do not commit local env.

Co-authored-by: Sander Vonk <sandervonk@users.noreply.github.com>
---
 .env | 62 ------------------------------------------------------------
 1 file changed, 62 deletions(-)
 delete mode 100644 .env

diff --git a/.env b/.env
deleted file mode 100644
index 07363569..00000000
--- a/.env
+++ /dev/null
@@ -1,62 +0,0 @@
-# the main brand name shown in files
-VUE_APP_BRAND_NAME_LONG=Task Tracker [BETA]
-# the short name used in the app
-VUE_APP_BRAND_NAME_SHORT=[BETA]
-# the main brand URL (without trailing slash)
-VUE_APP_BRAND_URL=http://localhost:8080
-# the main brand homepage used for pwa, etc (without trailing slash) 
-VUE_APP_BRAND_HOMEPAGE=http://localhost:8080
-# the main brand domain (without subdomain)
-VUE_APP_BRAND_DOMAIN=localhost:8080
-# excluding the hash due to limitations in the .env file
-VUE_APP_THEME_COLOR=f5c14b
-VUE_APP_THEME_ACCENT_COLOR=000000
-VUE_APP_THEME_ACCENT_COLOR_ALT=4c4c4c
-# the URL to download the sidebar
-VUE_APP_SIDEBAR_DOWNLOAD_URL=/download/mvtt-sidebar.zip
-
-# the domain for the API
-VUE_APP_BRAND_DOMAIN__API=api.mvtt.app
-# the domain that redirects to the class add view
-VUE_APP_BRAND_DOMAIN__ADDCLASS=localhost:8080/add
-# the domain that redirects to the class view
-VUE_APP_BRAND_DOMAIN__VIEWCLASS=localhost:8080/view
-# the domain that redirects to the task view
-VUE_APP_BRAND_DOMAIN__VIEWTASK=localhost:8080/view
-# the main mail address for the brand (used to send the invite mail)
-VUE_APP_BRAND_MAIL_ADDRESS=mail@mvtt.app
-
-# allowed domain hosts w/o outlink protection (either literal or *.domain.tld for wildcard)
-VUE_APP_BRAND_ALLOWED_HOSTS=mvla.net,*.mvla.net
-
-# console colors
-VUE_APP_THEME_CONSOLE_COLOR_BG=272727
-VUE_APP_THEME_CONSOLE_COLOR_TEXT=C9B092
-
-# the organization domain for user emails
-VUE_APP_ORG_DOMAIN=mvla.net
-# the organization (short) name
-VUE_APP_ORG_NAME=SCHOOL
-# links to relevant sites to be included in the basenav
-VUE_APP_ORG_LINKS=[["Docs", "https://localhost:8080/docs"]]
-# grade levels and their names
-VUE_APP_ORG_GRADES=[["student", "Student"]]
-# name for teacher acc
-VUE_APP_ORG_TEACHER_GRADE=Teacher
-
-# the API key for the Firebase project
-FIREBASE_apiKey=AIzaSyDGqqhApln4pxm4EynPCSkfwyK8aopjfCk
-# the domain for the Firebase auth
-FIREBASE_authDomain=auth.mvtt.app
-# the project ID of the Firebase project
-FIREBASE_projectId=mvtrack
-# the storage bucket for the Firebase project
-FIREBASE_storageBucket=mvtrack.appspot.com
-# the messaging sender ID for the Firebase project
-FIREBASE_messagingSenderId=1070634963357
-# the app ID for the Firebase project
-FIREBASE_appId=1:1070634963357:web:2a4abc725fff24a5199f74
-# the measurement ID for the Firebase project
-FIREBASE_measurementId=G-6LNX1KCR8E
-# the server region for the Firebase project
-FIREBASE_serverRegion=us-central1
\ No newline at end of file

From 908b0088307f3ecf9ba6705dce80e95ec28fd3aa Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Thu, 3 Sep 2026 01:50:12 +0000
Subject: [PATCH 4/5] Ignore local .env files (CI copies from .env.test)

Co-authored-by: Sander Vonk <sandervonk@users.noreply.github.com>
---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 448815d5..0f8167e6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,7 @@ node_modules
 /server
 
 # local env files
+.env
 .env.local
 .env.*.local
 

From 01b551dd7ec6c9e5a53eadd5683eb08096552a31 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Thu, 3 Sep 2026 01:50:32 +0000
Subject: [PATCH 5/5] Clarify join-class test import comment

Co-authored-by: Sander Vonk <sandervonk@users.noreply.github.com>
---
 scripts/test-join-class.mjs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/test-join-class.mjs b/scripts/test-join-class.mjs
index 77e0ebdc..1adaae77 100644
--- a/scripts/test-join-class.mjs
+++ b/scripts/test-join-class.mjs
@@ -1,6 +1,7 @@
 /**
  * Unit tests for P4 join-ref → bare classId resolution (Add Class / Onboarding).
  * Run: node --experimental-strip-types scripts/test-join-class.mjs
+ * (imports parseJoinRef from ../src/common/paths.ts)
  */
 import { parseJoinRef } from "../src/common/paths.ts";