sv

Author: nighca

spx-gui/AGENTS.md

@@ -35,6 +35,30 @@ Keep import statements in order:
 	- Enum names and enum members
 	- Vue component names
 
+### Identifier Resolution
+
+When working with backend unique string identifiers such as `username`, project owner, and project name, distinguish unresolved identifiers from canonical identifiers.
+
+* Treat values from route params, query params, and manual user input as unresolved identifiers.
+
+* Treat values from JWT token fields such as `username` as unresolved identifiers unless the current task explicitly establishes a stronger guarantee.
+
+* Treat backend-issued values from HTTP API responses as canonical identifiers.
+
+* Prefer naming unresolved values explicitly, such as `ownerInput`, `projectNameInput`, or similar names that make the unresolved nature obvious.
+
+* In models and resolved state, names like `owner`, `name`, and `username` should refer to canonical values.
+
+* Keep normal strict and case-sensitive equality (`===` / `!==`) for consuming identifiers. Do not spread ad hoc case-normalization logic across comparison sites.
+
+* Resolve unresolved identifiers at clear boundaries before consuming them. Typical resolution boundaries include project loading, user loading, and other backend-backed fetches.
+
+* Avoid storing unresolved identifiers on long-lived models as if they were already canonical. Prefer passing unresolved identifiers as load or resolve parameters, then writing canonical values onto the model after resolution.
+
+* Downstream logic should consume canonical values for behavior-sensitive checks. This includes ownership checks, permission checks, project reuse checks, local-cache decisions, and similar logic.
+
+* Cache keys and similar identity-scoping data may intentionally use unresolved identifiers when that preserves stable session scoping.
+
 ## TypeScript Testing
 
 * Use `describe` to group related tests.

spx-gui/src/components/agent-copilot/CopilotProvider.vue

@@ -84,7 +84,7 @@ export function useAgentCopilotCtx() {
  * Handles initialization of Copilot, MCP connections, and UI rendering.
  */
 import { reactive, inject, ref, provide, onBeforeUnmount, computed, type Ref, watch } from 'vue'
-import { computedShallowReactive } from '@/utils/utils'
+import { computedShallowReactive, untilNotNull } from '@/utils/utils'
 import { useI18n } from '@/utils/i18n'
 import { Copilot } from './copilot'
 import { CopilotController, type ICopilot } from './index'
@@ -95,7 +95,7 @@ import { ToolRegistry } from './mcp/registry'
 import { Collector } from './mcp/collector'
 import CopilotUI from './CopilotUI.vue'
 import { z } from 'zod'
-import { getSignedInUsername } from '@/stores/user'
+import { isSignedIn, useSignedInUser } from '@/stores/user'
 import { createProjectToolDescription, CreateProjectArgsSchema } from './mcp/definitions'
 import { getProject, Visibility } from '@/apis/project'
 import { useRouter } from 'vue-router'
@@ -114,6 +114,7 @@ const visible = ref(false)
 const mcpDebuggerVisible = ref(false)
 const showEnvPanel = ref(false)
 const router = useRouter()
+const signedInUser = useSignedInUser()
 
 const toggleEnvPanel = () => {
   showEnvPanel.value = !showEnvPanel.value
@@ -180,17 +181,18 @@ async function createProject(options: CreateProjectOptions) {
   const projectName = options.projectName
 
   // Check if user is signed in
-  const signedInUsername = getSignedInUsername()
-  if (signedInUsername == null) {
+  if (!isSignedIn()) {
     return {
       success: false,
       message: 'Please sign in to create a project'
     }
   }
 
+  const { username } = await untilNotNull(signedInUser)
+
   try {
     // Check if project already exists
-    const project = await getProject(signedInUsername, options.projectName)
+    const project = await getProject(username, options.projectName)
     if (project != null) {
       return {
         success: false,
@@ -201,7 +203,7 @@ async function createProject(options: CreateProjectOptions) {
     // Handle error checking project existence
   }
 
-  const project = new SpxProject(signedInUsername, projectName)
+  const project = new SpxProject(username, projectName)
   project.setVisibility(Visibility.Private)
 
   try {

spx-gui/src/components/agent-copilot/UserMessage.vue

@@ -7,7 +7,7 @@ const props = defineProps<{
   content: string
 }>()
 
-const { data: signedInUser } = useSignedInUser()
+const signedInUser = useSignedInUser()
 const avatarUrl = useAvatarUrl(() => signedInUser.value?.avatar)
 </script>
 

spx-gui/src/components/asset/gen/sprite/SpriteGen.vue

@@ -5,7 +5,7 @@ import { useI18n } from '@/utils/i18n'
 import { useNetwork } from '@/utils/network'
 import type { SpriteGen } from '@/models/spx/gen/sprite-gen'
 import type { Sprite } from '@/models/spx/sprite'
-import { getSignedInUsername } from '@/stores/user'
+import { useSignedInUser } from '@/stores/user'
 import { cloudHelpers } from '@/models/common/cloud'
 import { provideLocalEditorCtx } from '@/components/editor/EditorContextProvider.vue'
 import { EditorState } from '@/components/editor/editor-state'
@@ -24,7 +24,7 @@ const emit = defineEmits<{
 }>()
 
 const i18n = useI18n()
-const signedInUsername = computed(() => getSignedInUsername())
+const signedInUser = useSignedInUser()
 const { isOnline } = useNetwork()
 // Local cache is not really used in sprite gen, so a dummy implementation is sufficient.
 const localCache: ILocalCache = {
@@ -34,7 +34,7 @@ const localCache: ILocalCache = {
 }
 // We should override the state to avoid history operations caused by animation / costume changes within sprite gen.
 const editorStateInGen = useComputedDisposable(
-  () => new EditorState(i18n, props.gen.previewProject, isOnline, signedInUsername.value, cloudHelpers, localCache)
+  () => new EditorState(i18n, props.gen.previewProject, isOnline, signedInUser, cloudHelpers, localCache)
 )
 const editorCtxInGen = computedShallowReactive(() => ({
   project: props.gen.previewProject,

spx-gui/src/components/asset/library/AssetSaveModal.vue

@@ -39,7 +39,7 @@ const emit = defineEmits<{
   resolved: []
 }>()
 
-const { data: signedInUser } = useSignedInUser()
+const signedInUser = useSignedInUser()
 
 const user = computed(() => {
   const u = signedInUser.value

spx-gui/src/components/common/ListResultWrapper.vue

@@ -13,7 +13,7 @@ import { UILoading, UIError, UIEmpty } from '@/components/ui'
 import type { ByPage } from '@/apis/common'
 
 const props = defineProps<{
-  queryRet: QueryRet<T>
+  queryRet: QueryRet<T | null>
   height?: number
   /** Type of the list content */
   contentType?: 'project'

spx-gui/src/components/community/ProjectsSection.vue

@@ -46,7 +46,7 @@ type Context = 'home' | 'user' | 'project'
 
 defineProps<{
   linkTo?: string | null
-  queryRet: QueryRet<unknown[]>
+  queryRet: QueryRet<unknown[] | null>
   context: Context
   numInRow: number
 }>()

spx-gui/src/components/community/project/ReleaseHistory.vue

@@ -6,7 +6,7 @@ import { UITimeline, UITimelineItem, UILoading, UIError } from '@/components/ui'
 import TextView from '../TextView.vue'
 
 defineProps<{
-  queryRet: QueryRet<ProjectRelease[]>
+  queryRet: QueryRet<ProjectRelease[] | null>
 }>()
 </script>
 

spx-gui/src/components/community/user/FollowButton.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed } from 'vue'
-import { getSignedInUsername } from '@/stores/user'
+import { useSignedInUser } from '@/stores/user'
 import { UIButton } from '@/components/ui'
 import { useMessageHandle } from '@/utils/exception'
 import { useEnsureSignedIn } from '@/utils/user'
@@ -11,8 +11,9 @@ const props = defineProps<{
   name: string
 }>()
 
+const signedInUser = useSignedInUser()
 const followable = computed(() => {
-  const signedInUsername = getSignedInUsername()
+  const signedInUsername = signedInUser.value?.username ?? null
   return signedInUsername != null && props.name !== signedInUsername
 })
 

spx-gui/src/components/community/user/UserHeader.vue

@@ -4,7 +4,7 @@ import { useRoute, useRouter } from 'vue-router'
 import { type User } from '@/apis/user'
 import { useAvatarUrl } from '@/stores/user/avatar'
 import { useMessageHandle } from '@/utils/exception'
-import { getSignedInUsername } from '@/stores/user'
+import { useSignedInUser } from '@/stores/user'
 import { UIButton, UIImg, useModal } from '@/components/ui'
 import CommunityCard from '@/components/community/CommunityCard.vue'
 import TextView from '../TextView.vue'
@@ -21,7 +21,8 @@ const props = defineProps<{
 
 const router = useRouter()
 const route = useRoute()
-const isSignedInUser = computed(() => props.user.username === getSignedInUsername())
+const signedInUser = useSignedInUser()
+const isSignedInUser = computed(() => props.user.username === signedInUser.value?.username)
 const avatarUrl = useAvatarUrl(() => props.user.avatar)
 const coverImgUrl = computed(() => getCoverImgUrl(props.user.username))