synthos 0.8.0 → 0.10.0

package/src/models/anthropic.ts

@@ -1,5 +1,5 @@
 import Anthropic from '@anthropic-ai/sdk';
-import { AgentCompletion, completePrompt, PromptCompletionArgs, RequestError } from './types';
+import { AgentCompletion, completePrompt, PromptCompletionArgs, RequestError, isMultimodalContent } from './types';
 
 export interface AnthropicArgs {
     apiKey: string;
@@ -14,25 +14,44 @@ export interface AnthropicArgs {
  * Pure function — no SDK dependency.
  */
 export function buildAnthropicRequest(args: PromptCompletionArgs, defaultTemp: number): {
-    messages: { role: string; content: string }[];
-    system: string | undefined;
+    messages: { role: string; content: string | Anthropic.ContentBlockParam[] }[];
+    system: string | Anthropic.TextBlockParam[] | undefined;
     temperature: number;
+    outputConfig?: Anthropic.OutputConfig;
 } {
     const reqTemp = args.temperature ?? defaultTemp;
 
-    const messages: { role: string; content: string }[] = [];
+    const messages: { role: string; content: string | Anthropic.ContentBlockParam[] }[] = [];
     if (args.history) {
         for (const msg of args.history) {
             messages.push({ role: msg.role, content: msg.content });
         }
     }
 
-    const useJsonPrefill = args.jsonMode || args.jsonSchema;
+    // Build user content — multimodal when ContentBlock[] is provided
+    const promptContent = args.prompt.content;
+    let userContent: string | Anthropic.ContentBlockParam[];
+    if (isMultimodalContent(promptContent)) {
+        userContent = promptContent.map(block => {
+            if (block.type === 'text') {
+                return { type: 'text' as const, text: block.text };
+            }
+            return {
+                type: 'image' as const,
+                source: { type: 'base64' as const, media_type: block.mediaType as 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp', data: block.data },
+            };
+        });
+    } else {
+        userContent = promptContent;
+    }
+
+    // Structured output via output_config is incompatible with prefilling
+    const useJsonPrefill = !args.outputSchema && (args.jsonMode || args.jsonSchema);
     if (useJsonPrefill) {
-        messages.push({ role: 'user', content: args.prompt.content });
+        messages.push({ role: 'user', content: userContent });
         messages.push({ role: 'assistant', content: '{' });
     } else {
-        messages.push({ role: 'user', content: args.prompt.content });
+        messages.push({ role: 'user', content: userContent });
     }
 
     let system = args.system?.content;
@@ -41,7 +60,17 @@ export function buildAnthropicRequest(args: PromptCompletionArgs, defaultTemp: n
         system = system ? system + schemaInstruction : schemaInstruction;
     }
 
-    return { messages, system, temperature: reqTemp };
+    // Wrap system content with cache_control for prompt caching
+    const finalSystem: string | Anthropic.TextBlockParam[] | undefined = (system && args.cacheSystem)
+        ? [{ type: 'text' as const, text: system, cache_control: { type: 'ephemeral' as const } }]
+        : system;
+
+    // Structured output config for constrained decoding
+    const outputConfig: Anthropic.OutputConfig | undefined = args.outputSchema
+        ? { format: { type: 'json_schema', schema: args.outputSchema } }
+        : undefined;
+
+    return { messages, system: finalSystem, temperature: reqTemp, outputConfig };
 }
 
 export function anthropic(args: AnthropicArgs): completePrompt {
@@ -50,9 +79,9 @@ export function anthropic(args: AnthropicArgs): completePrompt {
     const client = new Anthropic({ apiKey, baseURL, maxRetries });
 
     return async (completionArgs: PromptCompletionArgs): Promise<AgentCompletion<string>> => {
-        const { messages, system: systemContent, temperature: reqTemp } = buildAnthropicRequest(completionArgs, temperature);
+        const { messages, system: systemContent, temperature: reqTemp, outputConfig } = buildAnthropicRequest(completionArgs, temperature);
 
-        const useJsonPrefill = completionArgs.jsonMode || completionArgs.jsonSchema;
+        const useJsonPrefill = !completionArgs.outputSchema && (completionArgs.jsonMode || completionArgs.jsonSchema);
 
         try {
             const stream = await client.messages.create({
@@ -62,6 +91,7 @@ export function anthropic(args: AnthropicArgs): completePrompt {
                 system: systemContent,
                 messages: messages as Anthropic.MessageParam[],
                 stream: true,
+                ...(outputConfig && { output_config: outputConfig }),
             });
 
             let text = '';

package/src/models/fireworksai.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { AgentCompletion, completePrompt, PromptCompletionArgs, RequestError } from './types';
+import { AgentCompletion, completePrompt, PromptCompletionArgs, RequestError, isMultimodalContent } from './types';
 
 export interface FireworksAIArgs {
     apiKey: string;
@@ -83,7 +83,14 @@ export function buildFireworksRequest(args: PromptCompletionArgs, defaultTemp: n
         }
     }
 
-    let userContent = args.prompt.content;
+    // Strip images — FireworksAI has no vision support; keep text only
+    const promptContent = args.prompt.content;
+    let userContent: string;
+    if (isMultimodalContent(promptContent)) {
+        userContent = promptContent.filter(b => b.type === 'text').map(b => (b as { text: string }).text).join('\n');
+    } else {
+        userContent = promptContent;
+    }
     if (useJson) {
         userContent += '\n\nRespond with valid JSON only. No markdown fences.';
     }

package/src/models/index.ts

@@ -1,4 +1,4 @@
-export { ProviderName, ProviderConfig, ModelEntry, Provider, SystemMessage, UserMessage, Message, AgentCompletion, completePrompt, PromptCompletionArgs, AgentArgs, RequestError } from './types';
+export { ProviderName, ProviderConfig, ModelEntry, Provider, SystemMessage, UserMessage, Message, AgentCompletion, completePrompt, PromptCompletionArgs, AgentArgs, RequestError, TextBlock, ImageBlock, ContentBlock, MessageContent, isMultimodalContent } from './types';
 export { AnthropicProvider, OpenAIProvider, PROVIDERS, getProvider, detectProvider } from './providers';
 export { anthropic, AnthropicArgs, buildAnthropicRequest } from './anthropic';
 export { openai, OpenaiArgs, buildOpenAIRequest } from './openai';

package/src/models/openai.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { AgentCompletion, completePrompt, PromptCompletionArgs, RequestError } from './types';
+import { AgentCompletion, completePrompt, PromptCompletionArgs, RequestError, isMultimodalContent } from './types';
 
 export interface OpenaiArgs {
     apiKey: string;
@@ -15,23 +15,43 @@ export interface OpenaiArgs {
  * Pure function — no SDK dependency.
  */
 export function buildOpenAIRequest(args: PromptCompletionArgs): {
-    input: { role: string; content: string }[];
+    input: { role: string; content: string | any[] }[];
     text?: { format: any };
 } {
-    const input: { role: string; content: string }[] = [];
+    const input: { role: string; content: string | any[] }[] = [];
     if (args.history) {
         for (const msg of args.history) {
             input.push({ role: msg.role, content: msg.content });
         }
     }
-    input.push({ role: 'user', content: args.prompt.content });
+
+    // Build user content — multimodal when ContentBlock[] is provided
+    const promptContent = args.prompt.content;
+    if (isMultimodalContent(promptContent)) {
+        const parts: any[] = promptContent.map(block => {
+            if (block.type === 'text') {
+                return { type: 'input_text', text: block.text };
+            }
+            return {
+                type: 'input_image',
+                image_url: `data:${block.mediaType};base64,${block.data}`,
+            };
+        });
+        input.push({ role: 'user', content: parts });
+    } else {
+        input.push({ role: 'user', content: promptContent });
+    }
 
     if (args.jsonMode || args.jsonSchema) {
-        const inputText = input.map(m => m.content).join(' ');
+        const inputText = input.map(m => typeof m.content === 'string' ? m.content : '').join(' ');
         if (!/json/i.test(inputText)) {
             const last = input[input.length - 1];
             if (last) {
-                last.content += '\nReturn JSON.';
+                if (typeof last.content === 'string') {
+                    last.content += '\nReturn JSON.';
+                } else if (Array.isArray(last.content)) {
+                    last.content.push({ type: 'input_text', text: '\nReturn JSON.' });
+                }
             }
         }
     }

package/src/models/types.ts

@@ -25,6 +25,30 @@ export interface Provider {
     detectModel(model: string): boolean;
 }
 
+// ---------------------------------------------------------------------------
+// Multimodal content
+// ---------------------------------------------------------------------------
+
+export interface TextBlock {
+    type: 'text';
+    text: string;
+}
+
+export interface ImageBlock {
+    type: 'image';
+    mediaType: string;
+    data: string;
+}
+
+export type ContentBlock = TextBlock | ImageBlock;
+
+export type MessageContent = string | ContentBlock[];
+
+/** Type guard: returns true when content is a multimodal ContentBlock array. */
+export function isMultimodalContent(content: MessageContent): content is ContentBlock[] {
+    return Array.isArray(content);
+}
+
 // ---------------------------------------------------------------------------
 // Messages
 // ---------------------------------------------------------------------------
@@ -39,8 +63,10 @@ export interface SystemMessage extends Message {
     role: 'system';
 }
 
-export interface UserMessage extends Message {
+export interface UserMessage {
     role: 'user';
+    content: MessageContent;
+    name?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -61,6 +87,10 @@ export interface PromptCompletionArgs {
     jsonMode?: boolean;
     /** JSON schema for structured output. When provided, the model is asked to return JSON conforming to this schema. */
     jsonSchema?: Record<string, unknown>;
+    /** When true, system content is wrapped with cache_control for Anthropic prompt caching. */
+    cacheSystem?: boolean;
+    /** JSON schema for structured output via constrained decoding (Anthropic output_config). */
+    outputSchema?: Record<string, unknown>;
 }
 
 export type completePrompt<TValue = string> = (args: PromptCompletionArgs) => Promise<AgentCompletion<TValue>>;

package/src/pages.ts

@@ -1,12 +1,29 @@
-import {checkIfExists, deleteFile, deleteFolder, ensureFolderExists, listFiles, listFolders, loadFile, saveFile} from './files';
+import {checkIfExists, listFolders, loadFile} from './files';
 import path from 'path';
+import { SynthOSConfig } from './init';
 
-// Page State Cache
-const _pages: { [name: string]: string } = {};
-
-export const REQUIRED_PAGES = ['builder', 'pages', 'settings', 'apis', 'scripts'];
+/**
+ * Derive the list of required page names by scanning *.html files
+ * across one or more requiredPages folders.
+ */
+export async function getRequiredPages(requiredPagesFolders: string[]): Promise<string[]> {
+    const result: string[] = [];
+    const seen = new Set<string>();
+    for (const folder of requiredPagesFolders) {
+        if (!await checkIfExists(folder)) continue;
+        const entries = await listFolders(folder);
+        for (const entry of entries) {
+            if (seen.has(entry)) continue;
+            if (await checkIfExists(path.join(folder, entry, 'page.html'))) {
+                seen.add(entry);
+                result.push(entry);
+            }
+        }
+    }
+    return result;
+}
 
-export const PAGE_VERSION = 2;
+export const PAGE_VERSION = 3;
 
 export interface PageInfo {
     name: string;
@@ -22,12 +39,15 @@ export interface PageInfo {
 
 export type PageMetadata = Omit<PageInfo, 'name'>;
 
-export async function loadPageMetadata(pagesFolder: string, name: string, fallbackFolder?: string): Promise<PageMetadata | undefined> {
-    // 1. Try user override: .synthos/pages/<name>/page.json
+export async function loadPageMetadata(config: SynthOSConfig, name: string, fallbackFolders?: string[]): Promise<PageMetadata | undefined> {
+    const pagesFolder = config.pagesFolder;
+    const sp = config.storageProvider;
+
+    // 1. Try user override: <localFolder>/pages/<name>/page.json
     const metadataPath = path.join(pagesFolder, 'pages', name, 'page.json');
-    if (await checkIfExists(metadataPath)) {
+    if (await sp.checkIfExists(metadataPath)) {
         try {
-            const raw = await loadFile(metadataPath);
+            const raw = await sp.loadFile(metadataPath);
             const parsed = JSON.parse(raw);
             return parseMetadata(parsed);
         } catch {
@@ -35,16 +55,18 @@ export async function loadPageMetadata(pagesFolder: string, name: string, fallba
         }
     }
 
-    // 2. Try fallback: fallbackFolder/<name>.json
-    if (fallbackFolder) {
-        const fallbackPath = path.join(fallbackFolder, `${name}.json`);
-        if (await checkIfExists(fallbackPath)) {
-            try {
-                const raw = await loadFile(fallbackPath);
-                const parsed = JSON.parse(raw);
-                return parseMetadata(parsed);
-            } catch {
-                // fall through
+    // 2. Try fallback folders: fallbackFolder/<name>/page.json (package content, always local fs)
+    if (fallbackFolders) {
+        for (const folder of fallbackFolders) {
+            const candidate = path.join(folder, name, 'page.json');
+            if (await checkIfExists(candidate)) {
+                try {
+                    const raw = await loadFile(candidate);
+                    const parsed = JSON.parse(raw);
+                    return parseMetadata(parsed);
+                } catch {
+                    // fall through
+                }
             }
         }
     }
@@ -66,10 +88,11 @@ export function parseMetadata(parsed: Record<string, unknown>): PageMetadata {
     };
 }
 
-export async function savePageMetadata(pagesFolder: string, name: string, metadata: PageMetadata): Promise<void> {
-    const pageFolder = path.join(pagesFolder, 'pages', name);
-    await ensureFolderExists(pageFolder);
-    await saveFile(path.join(pageFolder, 'page.json'), JSON.stringify(metadata, null, 4));
+export async function savePageMetadata(config: SynthOSConfig, name: string, metadata: PageMetadata): Promise<void> {
+    const sp = config.storageProvider;
+    const pageFolder = path.join(config.pagesFolder, 'pages', name);
+    await sp.ensureFolderExists(pageFolder);
+    await sp.saveFile(path.join(pageFolder, 'page.json'), JSON.stringify(metadata, null, 4));
 }
 
 const DEFAULT_METADATA: PageMetadata = {
@@ -83,16 +106,18 @@ const DEFAULT_METADATA: PageMetadata = {
     mode: 'unlocked',
 };
 
-export async function listPages(pagesFolder: string, fallbackPagesFolder: string): Promise<PageInfo[]> {
+export async function listPages(config: SynthOSConfig, fallbackPagesFolders: string[]): Promise<PageInfo[]> {
+    const pagesFolder = config.pagesFolder;
+    const sp = config.storageProvider;
     const pageMap = new Map<string, PageInfo>();
 
     // Folder-based pages under pages/ subdirectory
     const pagesSubdir = path.join(pagesFolder, 'pages');
-    if (await checkIfExists(pagesSubdir)) {
-        const folders = await listFolders(pagesSubdir);
+    if (await sp.checkIfExists(pagesSubdir)) {
+        const folders = await sp.listFolders(pagesSubdir);
         for (const folder of folders) {
-            if (await checkIfExists(path.join(pagesSubdir, folder, 'page.html'))) {
-                const metadata = await loadPageMetadata(pagesFolder, folder);
+            if (await sp.checkIfExists(path.join(pagesSubdir, folder, 'page.html'))) {
+                const metadata = await loadPageMetadata(config, folder);
                 pageMap.set(folder, {
                     name: folder,
                     ...(metadata ?? DEFAULT_METADATA),
@@ -102,7 +127,7 @@ export async function listPages(pagesFolder: string, fallbackPagesFolder: string
     }
 
     // Legacy flat .html files in root (v1 pages)
-    const flatFiles = (await listFiles(pagesFolder)).filter(file => file.endsWith('.html'));
+    const flatFiles = (await sp.listFiles(pagesFolder)).filter(file => file.endsWith('.html'));
     for (const file of flatFiles) {
         const name = file.replace(/\.html$/, '');
         if (!pageMap.has(name)) {
@@ -128,13 +153,15 @@ export async function listPages(pagesFolder: string, fallbackPagesFolder: string
         }
     }
 
-    // Add pages from fallback (required) pages folder
-    const fallbackFiles = (await listFiles(fallbackPagesFolder)).filter(file => file.endsWith('.html'));
-    for (const file of fallbackFiles) {
-        const name = file.replace(/\.html$/, '');
-        if (!pageMap.has(name)) {
-            // System page not yet in map — check for user override, then fallback .json
-            const metadata = await loadPageMetadata(pagesFolder, name, fallbackPagesFolder);
+    // Add pages from fallback (required) pages folders (package content, always local fs)
+    for (const folder of fallbackPagesFolders) {
+        if (!await checkIfExists(folder)) continue;
+        const dirs = await listFolders(folder);
+        for (const name of dirs) {
+            if (pageMap.has(name)) continue;
+            if (!await checkIfExists(path.join(folder, name, 'page.html'))) continue;
+            // System page not yet in map — check for user override, then fallback page.json
+            const metadata = await loadPageMetadata(config, name, fallbackPagesFolders);
             pageMap.set(name, {
                 name,
                 title: metadata?.title ?? '',
@@ -156,37 +183,45 @@ export async function listPages(pagesFolder: string, fallbackPagesFolder: string
     return entries;
 }
 
-export async function loadPageState(pagesFolder: string, name: string, reset: boolean): Promise<string|undefined> {
-    if (!_pages[name] || reset) {
-        // Try folder-based path under pages/ first, then fall back to flat file
-        const folderPath = path.join(pagesFolder, 'pages', name, 'page.html');
-        const flatPath = path.join(pagesFolder, `${name}.html`);
+export async function loadPageState(config: SynthOSConfig, name: string): Promise<string|undefined> {
+    const pagesFolder = config.pagesFolder;
+    const sp = config.storageProvider;
 
-        if (await checkIfExists(folderPath)) {
-            _pages[name] = await loadFile(folderPath);
-        } else if (await checkIfExists(flatPath)) {
-            _pages[name] = await loadFile(flatPath);
-        } else {
-            return undefined;
-        }
+    // Check for working-state version files first
+    const latestVersion = await getLatestVersion(config, name);
+    if (latestVersion > 0) {
+        const versionHtml = await loadPageVersion(config, name, latestVersion);
+        if (versionHtml) return versionHtml;
     }
 
-    return _pages[name];
+    // Fall back to saved baseline
+    const folderPath = path.join(pagesFolder, 'pages', name, 'page.html');
+    const directFolderPath = path.join(pagesFolder, name, 'page.html');
+    const flatPath = path.join(pagesFolder, `${name}.html`);
+
+    if (await sp.checkIfExists(folderPath)) {
+        return sp.loadFile(folderPath);
+    } else if (await sp.checkIfExists(directFolderPath)) {
+        return sp.loadFile(directFolderPath);
+    } else if (await sp.checkIfExists(flatPath)) {
+        return sp.loadFile(flatPath);
+    }
+    return undefined;
 }
 
 export function normalizePageName(name: string|undefined): string|undefined {
     return typeof name == 'string' && name.length > 0 ? name.replace(/[^a-z0-9\-_\[\]\(\)\{\}@#\$%&]/gi, '_').toLowerCase() : undefined;
 }
 
-export async function savePageState(pagesFolder: string, name: string, content: string, title?: string, categories?: string[]): Promise<void> {
-    _pages[name] = content;
-    const pageFolder = path.join(pagesFolder, 'pages', name);
-    await ensureFolderExists(pageFolder);
-    await saveFile(path.join(pageFolder, 'page.html'), content);
+export async function savePageState(config: SynthOSConfig, name: string, content: string, title?: string, categories?: string[]): Promise<void> {
+    const sp = config.storageProvider;
+    const pageFolder = path.join(config.pagesFolder, 'pages', name);
+    await sp.ensureFolderExists(pageFolder);
+    await sp.saveFile(path.join(pageFolder, 'page.html'), content);
 
     // Create page.json with full metadata if it doesn't exist
     const metadataPath = path.join(pageFolder, 'page.json');
-    if (!(await checkIfExists(metadataPath))) {
+    if (!(await sp.checkIfExists(metadataPath))) {
         const now = new Date().toISOString();
         const metadata: PageMetadata = {
             title: title ?? '',
@@ -198,45 +233,134 @@ export async function savePageState(pagesFolder: string, name: string, content:
             pageVersion: PAGE_VERSION,
             mode: 'unlocked',
         };
-        await saveFile(metadataPath, JSON.stringify(metadata, null, 4));
+        await sp.saveFile(metadataPath, JSON.stringify(metadata, null, 4));
     }
 }
 
-export function updatePageState(name: string, content: string): void {
-    _pages[name] = content;
-}
+export async function deletePage(config: SynthOSConfig, name: string): Promise<void> {
+    const pagesFolder = config.pagesFolder;
+    const sp = config.storageProvider;
 
-export async function deletePage(pagesFolder: string, name: string): Promise<void> {
     // Delete folder-based page: <pagesFolder>/pages/<name>/
     const folderPath = path.join(pagesFolder, 'pages', name);
-    if (await checkIfExists(folderPath)) {
-        await deleteFolder(folderPath);
+    if (await sp.checkIfExists(folderPath)) {
+        await sp.deleteFolder(folderPath);
     }
 
     // Delete legacy flat file: <pagesFolder>/<name>.html
     const flatPath = path.join(pagesFolder, `${name}.html`);
-    if (await checkIfExists(flatPath)) {
-        await deleteFile(flatPath);
+    if (await sp.checkIfExists(flatPath)) {
+        await sp.deleteFile(flatPath);
+    }
+
+}
+
+// ---------------------------------------------------------------------------
+// Page versioning — per-edit version snapshots for undo support
+// ---------------------------------------------------------------------------
+
+/**
+ * Save a version snapshot: <pagesFolder>/pages/<name>/page.v<version>.html
+ */
+export async function savePageVersion(config: SynthOSConfig, name: string, version: number, html: string): Promise<void> {
+    const sp = config.storageProvider;
+    const pageFolder = path.join(config.pagesFolder, 'pages', name);
+    await sp.ensureFolderExists(pageFolder);
+    await sp.saveFile(path.join(pageFolder, `page.v${version}.html`), html);
+}
+
+/**
+ * Load a version snapshot (returns undefined if the file doesn't exist).
+ */
+export async function loadPageVersion(config: SynthOSConfig, name: string, version: number): Promise<string | undefined> {
+    const sp = config.storageProvider;
+    const filePath = path.join(config.pagesFolder, 'pages', name, `page.v${version}.html`);
+    if (!await sp.checkIfExists(filePath)) return undefined;
+    return sp.loadFile(filePath);
+}
+
+/**
+ * Scan page.v*.html files and return the highest version number (0 if none).
+ */
+export async function getLatestVersion(config: SynthOSConfig, name: string): Promise<number> {
+    const sp = config.storageProvider;
+    const pageFolder = path.join(config.pagesFolder, 'pages', name);
+    if (!await sp.checkIfExists(pageFolder)) return 0;
+    const files = await sp.listFiles(pageFolder);
+    let max = 0;
+    for (const file of files) {
+        const match = file.match(/^page\.v(\d+)\.html$/);
+        if (match) {
+            const v = parseInt(match[1], 10);
+            if (v > max) max = v;
+        }
+    }
+    return max;
+}
+
+/**
+ * Delete all page.v*.html version files for a page.
+ */
+export async function clearVersions(config: SynthOSConfig, name: string): Promise<void> {
+    const sp = config.storageProvider;
+    const pageFolder = path.join(config.pagesFolder, 'pages', name);
+    if (!await sp.checkIfExists(pageFolder)) return;
+    const files = await sp.listFiles(pageFolder);
+    for (const file of files) {
+        if (/^page\.v\d+\.html$/.test(file)) {
+            await sp.deleteFile(path.join(pageFolder, file));
+        }
     }
+}
 
-    // Clear in-memory cache
-    delete _pages[name];
+export interface CopyPageOptions {
+    copyTables?: boolean;   // default false
+    copyFiles?: boolean;    // default true
 }
 
 export async function copyPage(
-    pagesFolder: string,
+    config: SynthOSConfig,
     sourceName: string,
     targetName: string,
     title: string,
     categories: string[],
-    requiredPagesFolder: string
+    requiredPagesFolders: string[],
+    options?: CopyPageOptions
 ): Promise<void> {
-    // Load source HTML from user folder, then try required folder as fallback
-    let html = await loadPageState(pagesFolder, sourceName, true);
-    if (!html) {
-        const requiredPath = path.join(requiredPagesFolder, `${sourceName}.html`);
-        if (await checkIfExists(requiredPath)) {
-            html = await loadFile(requiredPath);
+    const pagesFolder = config.pagesFolder;
+    const sp = config.storageProvider;
+    const copyTables = options?.copyTables ?? false;
+    const cpFiles = options?.copyFiles ?? true;
+
+    // Resolve source page folder: user pages first, then required pages
+    let sourceFolder: string | undefined;
+    const userSourceFolder = path.join(pagesFolder, 'pages', sourceName);
+    if (await sp.checkIfExists(path.join(userSourceFolder, 'page.html'))) {
+        sourceFolder = userSourceFolder;
+    } else {
+        for (const folder of requiredPagesFolders) {
+            const candidate = path.join(folder, sourceName);
+            if (await checkIfExists(path.join(candidate, 'page.html'))) {
+                sourceFolder = candidate;
+                break;
+            }
+        }
+    }
+
+    // Load source HTML
+    let html: string | undefined;
+    if (sourceFolder) {
+        // Source could be user storage or package — try user first, fall back to local fs
+        if (sourceFolder === userSourceFolder) {
+            html = await sp.loadFile(path.join(sourceFolder, 'page.html'));
+        } else {
+            html = await loadFile(path.join(sourceFolder, 'page.html'));
+        }
+    } else {
+        // Try legacy flat file
+        const flatPath = path.join(pagesFolder, `${sourceName}.html`);
+        if (await sp.checkIfExists(flatPath)) {
+            html = await sp.loadFile(flatPath);
         }
     }
 
@@ -245,7 +369,7 @@ export async function copyPage(
     }
 
     // Save HTML to target (creates folder + page.html + page.json)
-    await savePageState(pagesFolder, targetName, html, title);
+    await savePageState(config, targetName, html, title);
 
     // Overwrite the generated metadata with provided title + categories
     const now = new Date().toISOString();
@@ -259,5 +383,34 @@ export async function copyPage(
         pageVersion: PAGE_VERSION,
         mode: 'unlocked',
     };
-    await savePageMetadata(pagesFolder, targetName, metadata);
+    await savePageMetadata(config, targetName, metadata);
+
+    // Copy additional content from source if a folder was resolved
+    if (sourceFolder) {
+        const targetFolder = path.join(pagesFolder, 'pages', targetName);
+
+        if (copyTables) {
+            // Source could be user or package folder — use appropriate listing
+            const entries = sourceFolder === userSourceFolder
+                ? await sp.listFolders(sourceFolder)
+                : await listFolders(sourceFolder);
+            for (const entry of entries) {
+                if (entry === 'files') continue; // handled separately
+                await sp.copyFolderRecursive(
+                    path.join(sourceFolder, entry),
+                    path.join(targetFolder, entry)
+                );
+            }
+        }
+
+        if (cpFiles) {
+            const filesDir = path.join(sourceFolder, 'files');
+            const filesDirExists = sourceFolder === userSourceFolder
+                ? await sp.checkIfExists(filesDir)
+                : await checkIfExists(filesDir);
+            if (filesDirExists) {
+                await sp.copyFolderRecursive(filesDir, path.join(targetFolder, 'files'));
+            }
+        }
+    }
 }