feat: support project font collection

spx-gui/src/apps/xbuilder/.env.production-cn

@@ -9,5 +9,6 @@ VITE_SENTRY_DSN="https://3b532e8d49bece95a4ad2d14c73c2e0b@o4509472134987776.inge
 VITE_SHOW_LICENSE="true"
 VITE_SHOW_TUTORIALS_ENTRY="true"
 VITE_DEFAULT_LANG="zh"
+VITE_DEFAULT_FONT_PREFERENCES="basic-chinese, default"
 
 VITE_ACCOUNT_OAUTH_CLIENT_ID="1"

spx-gui/src/apps/xbuilder/env.ts

@@ -5,6 +5,7 @@ export const disableAIGC = import.meta.env.VITE_DISABLE_AIGC === 'true'
 export const showLicense = import.meta.env.VITE_SHOW_LICENSE === 'true'
 export const showTutorialsEntry = import.meta.env.VITE_SHOW_TUTORIALS_ENTRY === 'true'
 export const defaultLang = (import.meta.env.VITE_DEFAULT_LANG as string) || 'en'
+export const defaultFontPreferences = (import.meta.env.VITE_DEFAULT_FONT_PREFERENCES as string) || 'default'
 export const accountOAuthClientId = import.meta.env.VITE_ACCOUNT_OAUTH_CLIENT_ID as string
 const sentryTracesSampleRate = parseFloat(import.meta.env.VITE_SENTRY_TRACES_SAMPLE_RATE as string)
 const sentryLSPSampleRate = parseFloat(import.meta.env.VITE_SENTRY_LSP_SAMPLE_RATE as string)

spx-gui/src/assets/fonts/basic-chinese/README.md

@@ -0,0 +1,4 @@
+# Noto Sans CJK SC
+
+`NotoSansCJKsc-Regular.otf` is the Noto Sans CJK SC Regular font from
+<https://github.com/notofonts/noto-cjk> and is licensed under the SIL Open Font License 1.1.

spx-gui/src/components/project/ProjectCreateModal.vue

@@ -64,6 +64,8 @@ import { cloudHelpers } from '@/models/common/cloud'
 import { xbpHelpers } from '@/models/common/xbp'
 import { SpxProject } from '@/models/spx/project'
 import { getDefaultProjectFile } from '@/components/project'
+import { defaultFontPreferences } from '@/apps/xbuilder/env'
+import { createBasicChineseFontFamily } from '@/models/spx/font'
 
 const props = defineProps<{
   remixSource?: string
@@ -111,6 +113,17 @@ const handleSubmit = useMessageHandle(
       const project = new SpxProject(signedInState.user.username, projectName)
       const serialized = await xbpHelpers.load(defaultProjectFile)
       await project.load(serialized)
+      project.fontPreferences = defaultFontPreferences
+      if (
+        defaultFontPreferences
+          .split(',')
+          .map((item) => item.trim())
+          .includes('basic-chinese')
+      ) {
+        project.fontCollection.splice(0, project.fontCollection.length, await createBasicChineseFontFamily())
+      } else {
+        project.fontCollection.splice(0)
+      }
       project.setDisplayName(projectName)
       project.setVisibility(Visibility.Private)
       const exported = await project.export()

spx-gui/src/models/spx/font.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+
+import { fromText, toConfig, type Files } from '../common/file'
+import { FontFamily } from './font'
+
+describe('FontFamily', () => {
+  it('loads and exports a single project font face', async () => {
+    const files: Files = {
+      'assets/fonts/basic-chinese/index.json': fromText('index.json', '{"faces":[{"path":"font.otf"}]}'),
+      'assets/fonts/basic-chinese/font.otf': fromText('font.otf', 'font')
+    }
+
+    const [fontFamily] = await FontFamily.loadAll(files)
+    expect(fontFamily.name).toBe('basic-chinese')
+    expect(await toConfig(fontFamily.export()['assets/fonts/basic-chinese/index.json']!)).toEqual({
+      faces: [{ path: 'font.otf' }]
+    })
+  })
+
+  it('rejects the reserved default family name', async () => {
+    const files: Files = {
+      'assets/fonts/default/index.json': fromText('index.json', '{"faces":[{"path":"font.otf"}]}'),
+      'assets/fonts/default/font.otf': fromText('font.otf', 'font')
+    }
+
+    await expect(FontFamily.loadAll(files)).rejects.toThrow('reserved')
+  })
+
+  it('rejects face paths outside their family directory', async () => {
+    const files: Files = {
+      'assets/fonts/basic-chinese/index.json': fromText('index.json', '{"faces":[{"path":"../font.otf"}]}'),
+      'assets/fonts/font.otf': fromText('font.otf', 'font')
+    }
+
+    await expect(FontFamily.loadAll(files)).rejects.toThrow('invalid font path')
+  })
+})

spx-gui/src/models/spx/font.ts

@@ -0,0 +1,84 @@
+import { reactive } from 'vue'
+
+import { join, resolve } from '@/utils/path'
+import { File, fromConfig, fromBlob, listDirs, toConfig, type Files } from '../common/file'
+
+export const fontAssetPath = 'assets/fonts'
+const fontConfigFileName = 'index.json'
+
+type RawFontConfig = {
+  faces?: { path?: string }[]
+}
+
+function validateFontFamilyName(name: string) {
+  if (name === '') throw new Error('font family name must not be empty')
+  if (name.includes(',') || name.includes("'") || name.includes('"')) {
+    throw new Error(`invalid font family name: ${name}`)
+  }
+  if (name.toLowerCase() === 'default') throw new Error('font family name default is reserved')
+}
+
+function validateFontPath(path: string, prefix: string) {
+  if (path === '' || path.startsWith('/') || path.split('/').includes('..')) {
+    throw new Error(`invalid font path: ${path}`)
+  }
+  const resolved = resolve(prefix, path)
+  if (!resolved.startsWith(prefix + '/')) throw new Error(`font path escapes family directory: ${path}`)
+  return resolved
+}
+
+export class FontFamily {
+  name: string
+  face: File
+  facePath: string
+
+  constructor(name: string, face: File, facePath = face.name) {
+    validateFontFamilyName(name)
+    this.name = name
+    this.face = face
+    this.facePath = facePath
+    return reactive(this) as this
+  }
+
+  static async load(name: string, files: Files) {
+    const prefix = join(fontAssetPath, name)
+    const configFile = files[join(prefix, fontConfigFileName)]
+    if (configFile == null) throw new Error(`font configuration not found for ${name}`)
+    const config = (await toConfig(configFile)) as RawFontConfig
+    if (config.faces?.length !== 1) throw new Error(`font family ${name} must have exactly one face`)
+    const facePath = config.faces[0].path
+    if (facePath == null) throw new Error(`font face path not found for ${name}`)
+    const face = files[validateFontPath(facePath, prefix)]
+    if (face == null) throw new Error(`font face not found for ${name}: ${facePath}`)
+    return new FontFamily(name, face, facePath)
+  }
+
+  static async loadAll(files: Files) {
+    const names = listDirs(files, fontAssetPath)
+    const normalizedNames = new Set<string>()
+    for (const name of names) {
+      validateFontFamilyName(name)
+      const normalized = name.toLowerCase()
+      if (normalizedNames.has(normalized)) throw new Error(`duplicate font family name: ${name}`)
+      normalizedNames.add(normalized)
+    }
+    return Promise.all(names.map((name) => FontFamily.load(name, files)))
+  }
+
+  export(): Files {
+    const prefix = join(fontAssetPath, this.name)
+    const config: RawFontConfig = { faces: [{ path: this.facePath }] }
+    return {
+      [join(prefix, fontConfigFileName)]: fromConfig(fontConfigFileName, config),
+      [validateFontPath(this.facePath, prefix)]: this.face
+    }
+  }
+}
+
+const basicChineseFontUrl = new URL('../../assets/fonts/basic-chinese/NotoSansCJKsc-Regular.otf', import.meta.url).href
+
+export async function createBasicChineseFontFamily() {
+  const response = await fetch(basicChineseFontUrl)
+  if (!response.ok) throw new Error(`failed to load basic Chinese font: ${response.status}`)
+  return new FontFamily('basic-chinese', fromBlob('NotoSansCJKsc-Regular.otf', await response.blob()))
+}

spx-gui/src/models/spx/project.test.ts

@@ -10,6 +10,7 @@ import * as hashHelper from '../common/hash'
 import { Backdrop } from './backdrop'
 import { Monitor } from './widget/monitor'
 import { SpxProject, projectConfigFilePath, type RawProjectConfig, type ScreenshotTaker } from './project'
+import { FontFamily } from './font'
 
 function mockFile(name = 'mocked') {
   return fromText(name, Math.random() + '')
@@ -101,6 +102,19 @@ describe('Project', () => {
     expect(hash).toBe(hash2)
   })
 
+  it('should preserve project font collection and preferences', async () => {
+    const project = new SpxProject()
+    project.fontPreferences = 'basic-chinese, default'
+    project.fontCollection.push(new FontFamily('basic-chinese', fromText('basic-chinese.otf', 'font')))
+
+    const files = project.exportFiles()
+    const loaded = new SpxProject()
+    await loaded.loadFiles(files)
+
+    expect(loaded.fontPreferences).toBe('basic-chinese, default')
+    expect(loaded.fontCollection.map((font) => font.name)).toEqual(['basic-chinese'])
+  })
+
   it('should export with existing thumbnail after screenshot taker unbound', async () => {
     const project = makeProject(null)
     const thumbnail = mockFile('thumbnail')

spx-gui/src/models/spx/project.ts

@@ -19,10 +19,12 @@ import { assign } from '../common'
 import { ensureValidSpriteName, ensureValidSoundName } from './common/asset-name'
 import { hashFiles } from '../common/hash'
 import { isProjectUsingAIInteraction } from '@/utils/project'
+import { setSvgFontPreferences } from '@/utils/img-rendering'
 import { defaultMapSize, Stage, type RawStageConfig } from './stage'
 import { DumbTilemap as Tilemap } from './tilemap'
 import { Sprite } from './sprite'
 import { Sound } from './sound'
+import { createBasicChineseFontFamily, FontFamily } from './font'
 import type { RawWidgetConfig } from './widget'
 import type { Metadata, IProject, PartialMetadata, ProjectSerialized } from '@/models/project'
 
@@ -84,6 +86,7 @@ export type RawProjectConfig = RawStageConfig &
      * Maximum FPS for the project.
      */
     maxFPS?: number
+    fontPreferences?: string
   }
 
 export type ScreenshotTaker = (
@@ -134,6 +137,8 @@ export class SpxProject extends Disposable implements IProject {
   // reference sounds by ID, and `removeSound` must clean up those cross-sprite references.
   sounds: Sound[]
   zorder: string[]
+  fontCollection: FontFamily[]
+  fontPreferences: string
 
   private aiDescription: string | null
   private aiDescriptionHash: string | null
@@ -368,13 +373,16 @@ export class SpxProject extends Disposable implements IProject {
       this.displayName = name
     }
     this.zorder = []
+    this.fontCollection = []
+    this.fontPreferences = 'default'
     this.stage = new Stage()
     this.sprites = []
     this.sounds = []
     this.addDisposer(() => {
       this.sprites.splice(0).forEach((s) => s.dispose())
       this.sounds.splice(0).forEach((s) => s.dispose())
       this.zorder = []
+      this.fontCollection.splice(0)
       this.stage.dispose()
       this.tilemap?.dispose()
       this.tilemap = null
@@ -425,11 +433,19 @@ export class SpxProject extends Disposable implements IProject {
       builder_soundOrder: soundOrder,
       tilemapPath,
       maxFPS,
+      fontPreferences,
       ...rawStageConfig
     } = config
 
     const sounds = await Sound.loadAll(files)
     const sprites = await Sprite.loadAll(files, { sounds })
+    const fontCollection = await FontFamily.loadAll(files)
+    if (fontPreferences == null && fontCollection.length === 0) {
+      fontCollection.push(await createBasicChineseFontFamily())
+      this.fontPreferences = 'basic-chinese, default'
+    } else {
+      this.fontPreferences = fontPreferences ?? 'default'
+    }
 
     const widgets: RawWidgetConfig[] = []
     const zorder: string[] = []
@@ -460,6 +476,7 @@ export class SpxProject extends Disposable implements IProject {
     this.sounds.splice(0).forEach((s) => s.dispose())
     orderBy(sounds, soundOrder).forEach((s) => this.addSound(s))
     this.zorder = zorder ?? []
+    this.fontCollection.splice(0, this.fontCollection.length, ...fontCollection)
 
     this.tilemap?.dispose()
     this.tilemap = tilemapPath != null ? await Tilemap.load(tilemapPath, assetsDir, files) : null
@@ -500,12 +517,15 @@ export class SpxProject extends Disposable implements IProject {
       zorder: [...zorderNames, ...(widgets ?? [])],
       builder_spriteOrder: this.sprites.map((s) => s.id),
       builder_soundOrder: this.sounds.map((s) => s.id),
-      maxFPS: this.maxFPS ?? 60 // Default is 60 FPS
+      maxFPS: this.maxFPS ?? 60, // Default is 60 FPS
+      fontPreferences: this.fontPreferences
     }
     files[projectConfigFilePath] = fromConfig(projectConfigFileName, config)
     Object.assign(files, stageFiles)
     Object.assign(files, ...this.sprites.map((s) => s.export({ sounds: this.sounds })))
     Object.assign(files, ...this.sounds.map((s) => s.export()))
+    Object.assign(files, ...this.fontCollection.map((fontFamily) => fontFamily.export()))
+    setSvgFontPreferences(files, this.fontPreferences, this.fontCollection)
     return files
   }
 

spx-gui/src/utils/img-rendering.test.ts

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { fromText } from '@/models/common/file'
-import { getRenderableImageUrl } from './img-rendering'
+import { getRenderableImageUrl, setSvgFontPreferences } from './img-rendering'
 import { injectScratchFontsToSvgText } from './scratch-svg-font'
 
 vi.mock('./scratch-svg-font', () => ({
@@ -86,4 +86,17 @@ describe('getRenderableImageUrl', () => {
     ctrl.abort()
     expect(URL.revokeObjectURL).toHaveBeenCalledWith(url)
   })
+
+  it('passes project font preferences to SVG rendering', async () => {
+    const file = fromText('costume.svg', '<svg><text>你好</text></svg>', { type: 'image/svg+xml' })
+    setSvgFontPreferences({ 'assets/costume.svg': file }, 'basic-chinese, default', [])
+
+    await getRenderableImageUrl(file, new AbortController().signal)
+
+    expect(injectScratchFontsToSvgText).toHaveBeenCalledWith(
+      '<svg><text>你好</text></svg>',
+      'basic-chinese, default',
+      expect.any(Map)
+    )
+  })
 })

spx-gui/src/utils/img-rendering.ts

@@ -5,11 +5,27 @@
 import { computed, ref, watch, type WatchSource } from 'vue'
 import { isSvgMimeType } from '@/utils/file'
 import { Cancelled } from '@/utils/exception'
-import type { File } from '@/models/common/file'
+import type { File, Files } from '@/models/common/file'
+import type { FontFamily } from '@/models/spx/font'
 import { injectScratchFontsToSvgText } from './scratch-svg-font'
 
 /** Cache for derived rendering SVG blobs with Scratch fonts injected (if needed), keyed by source `File`. */
 const derivedSvgCache = new WeakMap<File, Promise<Blob>>()
+type SvgFontConfig = {
+  fontPreferences: string
+  fontCollection: FontFamily[]
+}
+
+const svgFontConfig = new WeakMap<File, SvgFontConfig>()
+
+export function setSvgFontPreferences(files: Files, fontPreferences: string, fontCollection: FontFamily[]) {
+  Object.values(files).forEach((file) => {
+    if (file != null && isSvgMimeType(file.type)) {
+      derivedSvgCache.delete(file)
+      svgFontConfig.set(file, { fontPreferences, fontCollection })
+    }
+  })
+}
 
 /**
  * Get an image-resource URL for a `File`.
@@ -26,7 +42,12 @@ export async function getRenderableImageUrl(file: File, signal: AbortSignal) {
       .arrayBuffer()
       .then(async (ab) => {
         const svgText = new TextDecoder().decode(ab)
-        const injectedSvgText = await injectScratchFontsToSvgText(svgText)
+        const config = svgFontConfig.get(file)
+        const injectedSvgText = await injectScratchFontsToSvgText(
+          svgText,
+          config?.fontPreferences ?? 'default',
+          new Map(config?.fontCollection?.map((fontFamily) => [fontFamily.name, fontFamily.face]))
+        )
         return new Blob([injectedSvgText ?? ab], { type: 'image/svg+xml' })
       })
       .catch((e) => {