From e3d09c8b359fa9ed6a1ea1440110185a0b11b97e Mon Sep 17 00:00:00 2001
From: Steve Bauman <steven_bauman@outlook.com>
Date: Mon, 26 Oct 2026 13:47:11 -0400
Subject: [PATCH] Initialize and normalize projects before rendering

---
 app/components/Page.vue                    |  45 ++-----
 app/components/Preview.vue                 |  11 +-
 app/composables/usePreview.js              |   7 +-
 app/composables/useProjectStoreFactory.js  |  21 +---
 app/composables/useProjectStores.js        |  74 +++++------
 app/composables/useSettings.js             |  98 +--------------
 app/lib/project.js                         |  77 ++++++++++++
 app/lib/settings.js                        |  97 +++++++++++++++
 app/plugins/project-storage.client.js      |   5 +-
 tests/components/Preview.test.js           |  12 +-
 tests/composables/usePreview.test.js       |  14 ++-
 tests/composables/useProjectImport.test.js |  54 ++++++++
 tests/composables/useProjectStores.test.js |  16 +--
 tests/lib/project.test.js                  | 138 +++++++++++++++++++++
 tests/plugins/project-storage.test.js      |  11 +-
 15 files changed, 451 insertions(+), 229 deletions(-)
 create mode 100644 app/lib/project.js
 create mode 100644 app/lib/settings.js
 create mode 100644 tests/composables/useProjectImport.test.js
 create mode 100644 tests/lib/project.test.js

diff --git a/app/components/Page.vue b/app/components/Page.vue
index 66f4382..7d97076 100644
--- a/app/components/Page.vue
+++ b/app/components/Page.vue
@@ -68,12 +68,12 @@
 
 <script setup>
 import { ref, toRefs, watch, nextTick, computed, onMounted } from 'vue';
-import { v4 as uuid } from 'uuid';
+import { createEditor } from '~/lib/project';
 import useSplitView from '@/composables/useSplitView';
 import useEditorUtils from '~/composables/useEditorUtils';
 import { useWindowSize, useResizeObserver } from '@vueuse/core';
 import usePreferencesStore from '@/composables/usePreferencesStore';
-import { last, range, defaults } from 'lodash';
+import { last, range } from 'lodash';
 
 const props = defineProps({
     project: { type: Object, required: true },
@@ -95,13 +95,7 @@ const { width } = useWindowSize();
 
 const hasSmallScreen = computed(() => width.value <= 1024);
 
-const page = defaults(props.project.page, {
-    editors: [],
-    sizes: [40, 60],
-    editorSizes: [],
-    previousOrientation: null,
-    orientation: hasSmallScreen.value ? 'top' : 'left',
-});
+const page = props.project.page;
 
 const { sizes, editorSizes, editors, orientation, previousOrientation } = toRefs(page);
 
@@ -200,28 +194,14 @@ function removeEditor(id) {
     $bus.$emit('editors:refresh');
 }
 
-function makeEditor() {
-    const language = last(editors.value)?.language ?? preferences.editorLanguage;
-
-    return {
-        id: uuid(),
-        added: [],
-        removed: [],
-        focused: [],
-        language: language,
-        tabSize: preferences.editorTabSize,
-        value: preferences.editorInitialValue,
-    };
-}
-
 function addEditor() {
-    if (editors.value.length === 0) {
-        orientation.value = hasSmallScreen.value ? 'top' : preferences.editorOrientation;
-    }
-
     destroyEditorSplitView();
 
-    editors.value.push(makeEditor());
+    editors.value.push(
+        createEditor(preferences, {
+            language: last(editors.value)?.language ?? preferences.editorLanguage,
+        })
+    );
 
     $bus.$emit('editors:refresh');
 }
@@ -278,18 +258,9 @@ watch(orientation, async () => {
     refreshEditorsLayout();
 });
 
-// Here we are ensuring all editors that have been restored
-// from localstorage have any additional properties
-// that may have been added with future updates.
-editors.value = editors.value.map((editor) => defaults(editor, makeEditor()));
-
 watch(page, () => emit('update:touched'), { deep: true, flush: 'sync' });
 
 onMounted(() => {
-    if (editors.value.length === 0) {
-        addEditor();
-    }
-
     initPageSplitView();
     initEditorSplitView();
 });
diff --git a/app/components/Preview.vue b/app/components/Preview.vue
index 88d56ad..28467f7 100644
--- a/app/components/Preview.vue
+++ b/app/components/Preview.vue
@@ -275,15 +275,8 @@ const { scenes, applyScene } = useScenes();
 
 const { name, code, languages } = toRefs(props);
 
-const {
-    settings,
-    setWidth,
-    setHeight,
-    setAspectRatio,
-    resetWindowSize,
-    settingsDefaults,
-    setDefaultBackground,
-} = usePreview(props, { emit, pane });
+const { settings, setWidth, setHeight, setAspectRatio, resetWindowSize, setDefaultBackground } =
+    usePreview(props, { emit, pane });
 
 const {
     title,
diff --git a/app/composables/usePreview.js b/app/composables/usePreview.js
index 43323b0..cb14b98 100644
--- a/app/composables/usePreview.js
+++ b/app/composables/usePreview.js
@@ -1,14 +1,12 @@
-import useSettings from '@/composables/useSettings';
 import useAspectRatios from '@/composables/useAspectRatios';
 import { DEFAULT_BACKGROUND } from './useBackgrounds';
 import { watch, nextTick } from 'vue';
-import { cloneDeep, defaults, isEqual, omit } from 'lodash';
+import { cloneDeep, isEqual, omit } from 'lodash';
 
 export default function (props, { emit, pane }) {
     const { calculateAspectRatio } = useAspectRatios();
 
-    const { settingsDefaults } = useSettings();
-    const settings = defaults(props.settings, cloneDeep(settingsDefaults));
+    const settings = props.settings;
 
     watch(
         () => cloneDeep(omit(settings, ['image', 'themeType', 'themeBackground'])),
@@ -112,7 +110,6 @@ export default function (props, { emit, pane }) {
 
     return {
         settings,
-        settingsDefaults,
         setWidth,
         setHeight,
         resetWindowSize,
diff --git a/app/composables/useProjectStoreFactory.js b/app/composables/useProjectStoreFactory.js
index 375ea81..7a8a8d9 100644
--- a/app/composables/useProjectStoreFactory.js
+++ b/app/composables/useProjectStoreFactory.js
@@ -4,28 +4,13 @@ import { v4 as uuid } from 'uuid';
 import { defineStore } from 'pinia';
 import { namespace } from './useProjectStores';
 import useTemplateStore from './useTemplateStore';
+import usePreferencesStore from './usePreferencesStore';
+import { createProject } from '~/lib/project';
 import { cloneDeep, replace, omit } from 'lodash';
 
 export default function (id) {
     return defineStore(id, {
-        state: () => ({
-            version: '1.26.1',
-            modified: false,
-            page: {},
-            settings: {},
-            viewport: {
-                x: 0,
-                y: -150,
-                zoom: 1,
-            },
-            tab: {
-                kind: 'project',
-                order: 0,
-                name: null,
-                created_at: new Date(),
-                id: replace(id, namespace, ''),
-            },
-        }),
+        state: () => createProject(usePreferencesStore(), replace(id, namespace, '')),
 
         actions: {
             /**
diff --git a/app/composables/useProjectStores.js b/app/composables/useProjectStores.js
index 20fddd3..63a742d 100644
--- a/app/composables/useProjectStores.js
+++ b/app/composables/useProjectStores.js
@@ -3,14 +3,17 @@ import { fileDialog } from 'file-select-dialog';
 import useCurrentTab from './useCurrentTab';
 import useProjectStoreFactory from './useProjectStoreFactory';
 import { computed, nextTick, ref } from 'vue';
-import { has, head, sortBy, debounce, startsWith, cloneDeep } from 'lodash';
+import { head, sortBy, debounce, startsWith, cloneDeep } from 'lodash';
+import usePreferencesStore from './usePreferencesStore';
+import { createProject, normalizeProject } from '~/lib/project';
+import { toast } from 'vue-sonner';
 
 export const namespace = 'pages/';
 
 const maxRecentlyClosedProjects = 20;
 
 export default function () {
-    const { $bus } = useNuxtApp();
+    const preferences = usePreferencesStore();
 
     const { currentTab, setTabFromProject } = useCurrentTab();
 
@@ -62,31 +65,14 @@ export default function () {
      * @param {*} data
      */
     function syncProjectStateWithData(project, data) {
+        const normalized = normalizeProject(data, preferences);
+
         project.$patch((state) => {
-            state.page = data.page;
-            state.settings = data.settings;
-            state.tab.name = data.tab.name;
-            state.tab.saved_project_id = data.tab.saved_project_id;
-            state.tab.kind = data.tab.kind ?? 'project';
-
-            // Here we will port old editors that don't contain the newly added
-            // properties from the new v1.9.0 update. v1.9.0 has also added a
-            // new "version" property to projects, so we can target this
-            // property to determine if we need to add these attributes.
-            if (!data.hasOwnProperty('version')) {
-                state.page.editors.map((editor) => {
-                    editor.added = [];
-                    editor.removed = [];
-                    editor.focused = [];
-                });
-            }
-
-            // Here we will port the old orientation setting,
-            // so templates that were saved in an older
-            // version can be restored properly.
-            if (['portrait', 'landscape'].includes(state.page.orientation)) {
-                state.page.orientation = 'left';
-            }
+            state.page = normalized.page;
+            state.settings = normalized.settings;
+            state.tab.name = normalized.tab.name;
+            state.tab.saved_project_id = normalized.tab.saved_project_id;
+            state.tab.kind = normalized.tab.kind;
         });
     }
 
@@ -98,7 +84,14 @@ export default function () {
      * @returns {Store}
      */
     function startProjectFromScratch(project) {
-        project.$patch((state) => (state.tab.kind = 'project'));
+        const initial = createProject(preferences, project.tab.id);
+
+        project.$patch((state) => {
+            state.page = initial.page;
+            state.settings = initial.settings;
+            state.modified = true;
+            state.tab.kind = 'project';
+        });
 
         return project;
     }
@@ -112,7 +105,7 @@ export default function () {
      * @returns {Store}
      */
     function startProjectFromTemplate(project, template) {
-        syncProjectStateWithData(project, cloneDeep(template));
+        syncProjectStateWithData(project, template);
 
         project.$patch((state) => {
             state.tab.kind = 'project';
@@ -134,25 +127,16 @@ export default function () {
             return;
         }
 
-        const data = await new Response(file).json();
-
-        ['tab', 'page', 'settings'].forEach((requiredKey) => {
-            if (!has(data, requiredKey)) {
-                $bus.$emit(
-                    'alert',
-                    'danger',
-                    'Error importing configuration. Required data is missing.'
-                );
-
-                console.error(`The configuration file is missing the data key [${requiredKey}].`);
-            }
-        });
-
-        const project = addNewProject();
+        let data;
 
-        if (project) {
-            syncProjectStateWithData(project, data);
+        try {
+            data = normalizeProject(await new Response(file).json(), preferences);
+        } catch (error) {
+            toast.error(`Unable to import project. ${error.message}`);
+            return;
         }
+
+        syncProjectStateWithData(addNewProject(), data);
     }
 
     /**
diff --git a/app/composables/useSettings.js b/app/composables/useSettings.js
index 060e39e..38359cf 100644
--- a/app/composables/useSettings.js
+++ b/app/composables/useSettings.js
@@ -1,104 +1,10 @@
 import { reactive } from 'vue';
 import { cloneDeep, defaults as applyDefaults, pick } from 'lodash';
-import { DEFAULT_BACKGROUND } from '~/composables/useBackgrounds';
+import { createSettings } from '~/lib/settings';
 import usePreferencesStore from '~/composables/usePreferencesStore';
 
 export default function (defaults = {}) {
-    const preferences = usePreferencesStore();
-
-    const settingsDefaults = {
-        title: '',
-        width: 500,
-        height: 300,
-        position: 'center',
-        landscape: false,
-        showHeader: true,
-        showHeaderAccent: false,
-        showTitle: true,
-        showMenu: true,
-        showDividers: true,
-        showColorMenu: false,
-        headerTitleColor: {
-            red: 156,
-            green: 163,
-            blue: 175,
-            alpha: 1,
-        },
-        showLineNumbers: false,
-        scene: 'none',
-        background: DEFAULT_BACKGROUND,
-        backgroundColor: null,
-
-        themeType: 'dark',
-        themeOpacity: 1.0,
-        themeName: preferences.previewThemeName,
-        themeBackground: '#fff',
-        aspectRatio: null,
-
-        lockWindowSize: preferences.previewLockToWindow,
-        lockWindowPaddingX: preferences.previewLockToWindowPaddingX,
-        lockWindowPaddingY: preferences.previewLockToWindowPaddingY,
-
-        fontSize: preferences.previewFontSize,
-        fontFamily: preferences.previewFontFamily,
-        lineHeight: preferences.previewLineHeight,
-
-        padding: 16,
-        paddingLocked: true,
-        paddingTop: 16,
-        paddingBottom: 16,
-        paddingLeft: 16,
-        paddingRight: 16,
-
-        marginTop: 0,
-        marginBottom: 0,
-        marginLeft: 0,
-        marginRight: 0,
-
-        image: null,
-        scale: 1.0,
-
-        showBorder: false,
-
-        borderRadius: 12,
-        borderRadiusLocked: true,
-        borderRadiusTopLeft: 12,
-        borderRadiusTopRight: 12,
-        borderRadiusBottomLeft: 12,
-        borderRadiusBottomRight: 12,
-        borderWidth: 2,
-        borderColor: {
-            red: 0,
-            green: 0,
-            blue: 0,
-            alpha: 1,
-        },
-
-        showShadow: true,
-        shadowX: 0,
-        shadowY: 10,
-        shadowBlur: 10,
-        shadowSpread: -5,
-        shadowColor: {
-            red: 0,
-            green: 0,
-            blue: 0,
-            alpha: 0.3,
-        },
-
-        showShine: false,
-        shineWidth: 50,
-        shineHeight: 172,
-        shineOpacity: 0.03,
-
-        showSocialBadge: preferences.showSocialBadge,
-        socialType: preferences.socialType,
-        socialUsername: preferences.socialUsername,
-        socialDisplayName: preferences.socialDisplayName,
-        socialPosition: preferences.socialPosition,
-        socialBorderRadius: 25,
-        socialLocation: 'outside',
-    };
+    const settingsDefaults = createSettings(usePreferencesStore());
 
     const settings = reactive(
         pick(applyDefaults(cloneDeep(defaults), settingsDefaults), Object.keys(settingsDefaults))
diff --git a/app/lib/project.js b/app/lib/project.js
new file mode 100644
index 0000000..a020d64
--- /dev/null
+++ b/app/lib/project.js
@@ -0,0 +1,77 @@
+import { v4 as uuid } from 'uuid';
+import { cloneDeep, defaults, isPlainObject } from 'lodash';
+import { createSettings } from './settings';
+
+export function createEditor(preferences, attributes = {}) {
+    return defaults(cloneDeep(attributes), {
+        id: uuid(),
+        added: [],
+        removed: [],
+        focused: [],
+        language: preferences.editorLanguage,
+        tabSize: preferences.editorTabSize,
+        value: preferences.editorInitialValue,
+    });
+}
+
+export function createProject(preferences, id = uuid()) {
+    return {
+        version: '1.26.1',
+        modified: false,
+        page: {
+            editors: [createEditor(preferences)],
+            sizes: [40, 60],
+            editorSizes: [100],
+            previousOrientation: null,
+            orientation: preferences.editorOrientation,
+        },
+        settings: createSettings(preferences),
+        viewport: { x: 0, y: -150, zoom: 1 },
+        tab: {
+            kind: 'project',
+            order: 0,
+            name: null,
+            created_at: new Date(),
+            id,
+        },
+    };
+}
+
+export function normalizeProject(data, preferences) {
+    if (
+        !isPlainObject(data) ||
+        !['tab', 'page', 'settings'].every((key) => isPlainObject(data[key]))
+    ) {
+        throw new Error('The project must contain tab, page, and settings objects.');
+    }
+
+    if (
+        data.page.editors !== undefined &&
+        (!Array.isArray(data.page.editors) || !data.page.editors.every(isPlainObject))
+    ) {
+        throw new Error('The project editors must be an array of objects.');
+    }
+
+    const initial = createProject(preferences, data.tab.id);
+    const project = defaults(cloneDeep(data), initial);
+
+    project.tab = defaults(project.tab, initial.tab);
+    project.page = defaults(project.page, initial.page);
+    project.settings = defaults(project.settings, initial.settings);
+    project.viewport = defaults(project.viewport, initial.viewport);
+    project.page.editors = project.page.editors.length
+        ? project.page.editors.map((editor) => createEditor(preferences, editor))
+        : initial.page.editors;
+
+    if (!data.page.editorSizes?.length) {
+        project.page.editorSizes = project.page.editors.map(
+            () => 100 / project.page.editors.length
+        );
+    }
+
+    if (['portrait', 'landscape'].includes(project.page.orientation)) {
+        project.page.orientation = 'left';
+    }
+
+    return project;
+}
diff --git a/app/lib/settings.js b/app/lib/settings.js
new file mode 100644
index 0000000..ee6e9b0
--- /dev/null
+++ b/app/lib/settings.js
@@ -0,0 +1,97 @@
+import { DEFAULT_BACKGROUND } from '~/composables/useBackgrounds';
+
+export function createSettings(preferences) {
+    return {
+        title: '',
+        width: 500,
+        height: 300,
+        position: 'center',
+        landscape: false,
+        showHeader: true,
+        showHeaderAccent: false,
+        showTitle: true,
+        showMenu: true,
+        showDividers: true,
+        showColorMenu: false,
+        headerTitleColor: {
+            red: 156,
+            green: 163,
+            blue: 175,
+            alpha: 1,
+        },
+        showLineNumbers: false,
+        scene: 'none',
+        background: DEFAULT_BACKGROUND,
+        backgroundColor: null,
+
+        themeType: 'dark',
+        themeOpacity: 1.0,
+        themeName: preferences.previewThemeName,
+        themeBackground: '#fff',
+        aspectRatio: null,
+
+        lockWindowSize: preferences.previewLockToWindow,
+        lockWindowPaddingX: preferences.previewLockToWindowPaddingX,
+        lockWindowPaddingY: preferences.previewLockToWindowPaddingY,
+
+        fontSize: preferences.previewFontSize,
+        fontFamily: preferences.previewFontFamily,
+        lineHeight: preferences.previewLineHeight,
+
+        padding: 16,
+        paddingLocked: true,
+        paddingTop: 16,
+        paddingBottom: 16,
+        paddingLeft: 16,
+        paddingRight: 16,
+
+        marginTop: 0,
+        marginBottom: 0,
+        marginLeft: 0,
+        marginRight: 0,
+
+        image: null,
+        scale: 1.0,
+
+        showBorder: false,
+
+        borderRadius: 12,
+        borderRadiusLocked: true,
+        borderRadiusTopLeft: 12,
+        borderRadiusTopRight: 12,
+        borderRadiusBottomLeft: 12,
+        borderRadiusBottomRight: 12,
+        borderWidth: 2,
+        borderColor: {
+            red: 0,
+            green: 0,
+            blue: 0,
+            alpha: 1,
+        },
+
+        showShadow: true,
+        shadowX: 0,
+        shadowY: 10,
+        shadowBlur: 10,
+        shadowSpread: -5,
+        shadowColor: {
+            red: 0,
+            green: 0,
+            blue: 0,
+            alpha: 0.3,
+        },
+
+        showShine: false,
+        shineWidth: 50,
+        shineHeight: 172,
+        shineOpacity: 0.03,
+
+        showSocialBadge: preferences.showSocialBadge,
+        socialType: preferences.socialType,
+        socialUsername: preferences.socialUsername,
+        socialDisplayName: preferences.socialDisplayName,
+        socialPosition: preferences.socialPosition,
+        socialBorderRadius: 25,
+        socialLocation: 'outside',
+    };
+}
diff --git a/app/plugins/project-storage.client.js b/app/plugins/project-storage.client.js
index 8cffb6c..ec49520 100644
--- a/app/plugins/project-storage.client.js
+++ b/app/plugins/project-storage.client.js
@@ -1,4 +1,6 @@
 import { debounce } from 'lodash';
+import { normalizeProject } from '~/lib/project';
+import usePreferencesStore from '~/composables/usePreferencesStore';
 import { namespace } from '~/composables/useProjectStores';
 
 export default defineNuxtPlugin({
@@ -12,7 +14,8 @@ export default defineNuxtPlugin({
             try {
                 const stored = localStorage.getItem(store.$id);
 
-                if (stored) store.$patch(JSON.parse(stored));
+                if (stored)
+                    store.$patch(normalizeProject(JSON.parse(stored), usePreferencesStore($pinia)));
             } catch (error) {
                 console.error('Unable to restore project.', error);
             }
diff --git a/tests/components/Preview.test.js b/tests/components/Preview.test.js
index 1777c19..f5aa2da 100644
--- a/tests/components/Preview.test.js
+++ b/tests/components/Preview.test.js
@@ -2,6 +2,8 @@ import { flushPromises, mount } from '@vue/test-utils';
 import { defineComponent, nextTick, reactive, ref } from 'vue';
 import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
 import Preview from '~/components/Preview.vue';
+import { createSettings } from '~/lib/settings';
+import { defaults as preferences } from '~/composables/usePreferencesStore';
 
 const highlighted = { blocks: [], themeType: 'dark', themeBackground: '#000000' };
 const buildCodeBlocks = vi.hoisted(() => vi.fn());
@@ -39,7 +41,7 @@ afterEach(() => {
 describe('Preview', () => {
     it('keeps appearance changes in the supplied settings when switching tabs', async () => {
         const showing = ref(true);
-        const settings = reactive({});
+        const settings = reactive(createSettings(preferences));
         const wrapper = mount(
             defineComponent({
                 components: { Preview },
@@ -68,7 +70,7 @@ describe('Preview', () => {
         vi.useFakeTimers();
         const wrapper = mount(Preview, {
             shallow: true,
-            props: { code: [], settings: {}, viewport: {}, languages: [] },
+            props: { code: [], settings: createSettings(preferences), viewport: {}, languages: [] },
         });
         await flushPromises();
         buildCodeBlocks.mockClear();
@@ -94,7 +96,7 @@ describe('Preview', () => {
         const wrapper = mount(Preview, {
             shallow: true,
             attachTo: document.body,
-            props: { code: [], settings: {}, viewport: {}, languages: [] },
+            props: { code: [], settings: createSettings(preferences), viewport: {}, languages: [] },
         });
         wrapper.vm.$.setupState.settings.showShadow = false;
         await nextTick();
@@ -110,7 +112,7 @@ describe('Preview', () => {
         const wrapper = mount(Preview, {
             shallow: true,
             attachTo: document.body,
-            props: { code: [], settings: {}, viewport: {}, languages: [] },
+            props: { code: [], settings: createSettings(preferences), viewport: {}, languages: [] },
         });
         await flushPromises();
         let finish;
@@ -141,7 +143,7 @@ describe('Preview', () => {
         const wrapper = mount(Preview, {
             shallow: true,
             attachTo: document.body,
-            props: { code: [], settings: {}, viewport: {}, languages: [] },
+            props: { code: [], settings: createSettings(preferences), viewport: {}, languages: [] },
         });
         await flushPromises();
         let finish;
diff --git a/tests/composables/usePreview.test.js b/tests/composables/usePreview.test.js
index 279b710..35989c5 100644
--- a/tests/composables/usePreview.test.js
+++ b/tests/composables/usePreview.test.js
@@ -1,11 +1,16 @@
 import { describe, it, expect, vi } from 'vitest';
 import { nextTick, reactive, ref } from 'vue';
 import usePreview from '~/composables/usePreview';
+import { createSettings } from '~/lib/settings';
+import { defaults as preferences } from '~/composables/usePreferencesStore';
 
 describe('usePreview', () => {
     it('marks appearance changes as unsaved after every edit', async () => {
         const emit = vi.fn();
-        const { settings } = usePreview(reactive({ settings: {} }), { emit, pane: ref(null) });
+        const { settings } = usePreview(reactive({ settings: createSettings(preferences) }), {
+            emit,
+            pane: ref(null),
+        });
 
         await nextTick();
         expect(emit).not.toHaveBeenCalled();
@@ -21,7 +26,7 @@ describe('usePreview', () => {
     });
 
     it('updates the supplied settings and dependent values before returning to the caller', () => {
-        const props = reactive({ settings: { showHeader: true } });
+        const props = reactive({ settings: createSettings(preferences) });
         const emit = vi.fn();
         const { settings } = usePreview(props, { emit, pane: ref(null) });
 
@@ -39,7 +44,10 @@ describe('usePreview', () => {
 
     it('does not mark generated preview metadata as unsaved', async () => {
         const emit = vi.fn();
-        const { settings } = usePreview(reactive({ settings: {} }), { emit, pane: ref(null) });
+        const { settings } = usePreview(reactive({ settings: createSettings(preferences) }), {
+            emit,
+            pane: ref(null),
+        });
 
         settings.image = 'generated-thumbnail';
         settings.themeType = 'light';
diff --git a/tests/composables/useProjectImport.test.js b/tests/composables/useProjectImport.test.js
new file mode 100644
index 0000000..352ac0e
--- /dev/null
+++ b/tests/composables/useProjectImport.test.js
@@ -0,0 +1,54 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { fileDialog } from 'file-select-dialog';
+import { toast } from 'vue-sonner';
+import useProjectStores from '~/composables/useProjectStores';
+
+vi.mock('file-select-dialog', () => ({ fileDialog: vi.fn() }));
+vi.mock('vue-sonner', () => ({ toast: { error: vi.fn() } }));
+
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+
+describe('project imports', () => {
+    it('opens an older configuration with complete editor and preview settings', async () => {
+        const source = {
+            tab: { name: 'Imported project' },
+            page: { orientation: 'landscape', editors: [{ value: 'imported code' }] },
+            settings: { fontSize: 24 },
+        };
+        fileDialog.mockResolvedValue([JSON.stringify(source)]);
+        const { projects, importNewProject } = useProjectStores();
+
+        await importNewProject();
+
+        expect(projects.value).toHaveLength(1);
+        expect(projects.value[0].tab.kind).toBe('project');
+        expect(projects.value[0].tab.name).toBe('Imported project');
+        expect(projects.value[0].page.orientation).toBe('left');
+        expect(projects.value[0].page.editors[0]).toMatchObject({
+            id: expect.any(String),
+            value: 'imported code',
+            added: [],
+            removed: [],
+            focused: [],
+        });
+        expect(projects.value[0].settings.fontSize).toBe(24);
+        expect(projects.value[0].settings.borderColor).toBeDefined();
+        expect(toast.error).not.toHaveBeenCalled();
+        projects.value[0].$dispose();
+    });
+
+    it.each(['{', '{"page":{}}', '{"tab":{},"page":{"editors":"invalid"},"settings":{}}'])(
+        'rejects invalid input without creating a tab: %s',
+        async (content) => {
+            fileDialog.mockResolvedValue([content]);
+            const { projects, importNewProject } = useProjectStores();
+
+            await importNewProject();
+
+            expect(projects.value).toHaveLength(0);
+            expect(toast.error).toHaveBeenCalledOnce();
+        }
+    );
+});
diff --git a/tests/composables/useProjectStores.test.js b/tests/composables/useProjectStores.test.js
index e3f5073..e032bc6 100644
--- a/tests/composables/useProjectStores.test.js
+++ b/tests/composables/useProjectStores.test.js
@@ -60,8 +60,8 @@ describe('useProjectStores', () => {
         expect(project.tab.id).not.toBe(template.tab.id);
         expect(project.tab.kind).toBe('project');
         expect(project.tab.name).toBe('Laravel Dark');
-        expect(project.page).toEqual(template.page);
-        expect(project.settings).toEqual(template.settings);
+        expect(project.page).toMatchObject(template.page);
+        expect(project.settings).toMatchObject(template.settings);
     });
 
     it('adds multiple projects', () => {
@@ -210,8 +210,8 @@ describe('useProjectStores', () => {
         ]);
         expect(reopened.tab.id).not.toBe(second.tab.id);
         expect(reopened.modified).toBe(true);
-        expect(reopened.page).toEqual(second.page);
-        expect(reopened.settings).toEqual(second.settings);
+        expect(reopened.page).toMatchObject(second.page);
+        expect(reopened.settings).toMatchObject(second.settings);
         expect(reopened.viewport).toEqual(second.viewport);
         expect(currentTab.value).toBe(reopened.tab.id);
     });
@@ -255,8 +255,8 @@ describe('useProjectStores', () => {
         expect(projects.value).toHaveLength(2);
         expect(projects.value[1].tab.id).not.toBe(project.tab.id);
         expect(duplicate.tab.name).toBe('Original Project');
-        expect(duplicate.page).toEqual(project.page);
-        expect(duplicate.settings).toEqual(project.settings);
+        expect(duplicate.page).toMatchObject(project.page);
+        expect(duplicate.settings).toMatchObject(project.settings);
         expect(currentTab.value).toBe(duplicate.tab.id);
     });
 
@@ -334,8 +334,8 @@ describe('useProjectStores', () => {
         expect(project.tab.id).not.toBe(savedProject.tab.id);
         expect(project.tab.saved_project_id).toBe(savedProject.tab.id);
         expect(project.tab.name).toBe('Saved Project');
-        expect(project.page).toEqual(savedProject.page);
-        expect(project.settings).toEqual(savedProject.settings);
+        expect(project.page).toMatchObject(savedProject.page);
+        expect(project.settings).toMatchObject(savedProject.settings);
         expect(project.modified).toBe(false);
         expect(currentTab.value).toBe(project.tab.id);
     });
diff --git a/tests/lib/project.test.js b/tests/lib/project.test.js
new file mode 100644
index 0000000..26d0bee
--- /dev/null
+++ b/tests/lib/project.test.js
@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest';
+import { createEditor, createProject, normalizeProject } from '~/lib/project';
+import { defaults as preferences } from '~/composables/usePreferencesStore';
+
+describe('projects', () => {
+    it('creates a complete project from the current preferences without rendering a component', () => {
+        const project = createProject(
+            {
+                ...preferences,
+                editorLanguage: 'javascript',
+                editorInitialValue: 'const count = 1;',
+                editorOrientation: 'right',
+                previewFontSize: 20,
+            },
+            'project-id'
+        );
+
+        expect(project.tab.id).toBe('project-id');
+        expect(project.page.orientation).toBe('right');
+        expect(project.page.sizes).toEqual([40, 60]);
+        expect(project.page.editors).toEqual([
+            expect.objectContaining({
+                id: expect.any(String),
+                language: 'javascript',
+                value: 'const count = 1;',
+                added: [],
+                removed: [],
+                focused: [],
+            }),
+        ]);
+        expect(project.settings.fontSize).toBe(20);
+        expect(project.settings.borderColor).toEqual({ red: 0, green: 0, blue: 0, alpha: 1 });
+    });
+
+    it('keeps mutable defaults independent between projects and editors', () => {
+        const first = createProject(preferences);
+        const second = createProject(preferences);
+        const editor = createEditor(preferences);
+
+        first.page.editors[0].added.push(2);
+        first.settings.borderColor.red = 200;
+        first.page.sizes[0] = 20;
+
+        expect(second.page.editors[0].added).toEqual([]);
+        expect(editor.added).toEqual([]);
+        expect(second.settings.borderColor.red).toBe(0);
+        expect(second.page.sizes).toEqual([40, 60]);
+        expect(second.tab.id).not.toBe(first.tab.id);
+    });
+
+    it('normalizes an old project without changing its source or existing content', () => {
+        const source = {
+            tab: { id: 'legacy', name: 'Old project' },
+            page: {
+                orientation: 'portrait',
+                editors: [{ id: 'old-editor', value: 'saved code', language: 'php' }],
+            },
+            settings: { fontSize: 22, background: 'custom-background' },
+        };
+        const project = normalizeProject(source, preferences);
+
+        expect(project.page.orientation).toBe('left');
+        expect(project.page.editors[0]).toMatchObject({
+            id: 'old-editor',
+            value: 'saved code',
+            language: 'php',
+            tabSize: 4,
+            added: [],
+            removed: [],
+            focused: [],
+        });
+        expect(project.settings.fontSize).toBe(22);
+        expect(project.settings.background).toBe('custom-background');
+        expect(project.settings.showHeader).toBe(true);
+        expect(project.viewport).toEqual({ x: 0, y: -150, zoom: 1 });
+        expect(source.page.orientation).toBe('portrait');
+        expect(source.page.editors[0].added).toBeUndefined();
+        expect(source.settings.showHeader).toBeUndefined();
+        expect(normalizeProject(project, preferences)).toEqual(project);
+    });
+
+    it('preserves saved layout, editor markers, and metadata when filling missing fields', () => {
+        const source = {
+            version: '1.26.1',
+            modified: true,
+            tab: { id: 'saved', saved_project_id: 'original', order: 3 },
+            viewport: { x: 20, y: 30, zoom: 1.5 },
+            page: {
+                orientation: 'bottom',
+                sizes: [30, 70],
+                editorSizes: [60, 40],
+                editors: [
+                    { id: 'one', value: 'first', added: [1], removed: [2], focused: [3] },
+                    { id: 'two', value: 'second', tabSize: 2 },
+                ],
+            },
+            settings: { width: 1200, height: 900, image: 'saved-thumbnail' },
+        };
+        const project = normalizeProject(source, preferences);
+
+        expect(project).toMatchObject(source);
+        expect(project.page.editors[1].focused).toEqual([]);
+        expect(project.settings.fontFamily).toBe(preferences.previewFontFamily);
+    });
+
+    it('assigns equal split sizes when an older project has multiple editors but no saved sizes', () => {
+        const project = normalizeProject(
+            {
+                tab: {},
+                page: { editors: [{ value: 'first' }, { value: 'second' }] },
+                settings: {},
+            },
+            preferences
+        );
+
+        expect(project.page.editorSizes).toEqual([50, 50]);
+    });
+
+    it('initializes an empty editor list before the project reaches a component', () => {
+        const project = normalizeProject(
+            { tab: {}, page: { editors: [] }, settings: {} },
+            preferences
+        );
+
+        expect(project.page.editors).toHaveLength(1);
+        expect(project.page.editors[0].value).toBe(preferences.editorInitialValue);
+    });
+
+    it.each([
+        null,
+        { page: {}, settings: {} },
+        { tab: {}, page: {}, settings: [] },
+        { tab: {}, page: { editors: 'code' }, settings: {} },
+        { tab: {}, page: { editors: [null] }, settings: {} },
+    ])('rejects invalid project structure: %j', (data) => {
+        expect(() => normalizeProject(data, preferences)).toThrow();
+    });
+});
diff --git a/tests/plugins/project-storage.test.js b/tests/plugins/project-storage.test.js
index 243b952..2b7a2b6 100644
--- a/tests/plugins/project-storage.test.js
+++ b/tests/plugins/project-storage.test.js
@@ -11,7 +11,14 @@ afterEach(() => {
 describe('project storage', () => {
     it('restores the existing project format and batches writes of the latest state', async () => {
         vi.useFakeTimers();
-        localStorage.setItem('pages/storage-batch', JSON.stringify({ page: { code: 'restored' } }));
+        localStorage.setItem(
+            'pages/storage-batch',
+            JSON.stringify({
+                tab: { id: 'storage-batch' },
+                settings: {},
+                page: { code: 'restored' },
+            })
+        );
         const pinia = createPinia();
         projectStorage.setup({ $pinia: pinia });
         createApp({}).use(pinia);
@@ -30,7 +37,7 @@ describe('project storage', () => {
 
         expect(setItem).toHaveBeenCalledExactlyOnceWith(
             'pages/storage-batch',
-            JSON.stringify({ page: { code: 'latest edit' } })
+            JSON.stringify(project.$state)
         );
         project.$dispose();
         localStorage.removeItem('pages/storage-batch');