jsgui3-server 0.0.151 → 0.0.152

package/serve-factory.js

@@ -6,6 +6,7 @@ const {
     ensure_route_leading_slash
 } = require('./serve-helpers');
 const lib_path = require('path');
+const Website = require('./website/website');
 const Webpage = require('./website/webpage');
 const HTTP_Webpage_Publisher = require('./publishers/http-webpage-publisher');
 const HTTP_SSE_Publisher = require('./publishers/http-sse-publisher');
@@ -14,6 +15,35 @@ const Process_Resource = require('./resources/process-resource');
 const Remote_Process_Resource = require('./resources/remote-process-resource');
 const { get_port_or_free } = require('./port-utils');
 
+const website_marker = Symbol.for('jsgui3.website');
+const webpage_marker = Symbol.for('jsgui3.webpage');
+
+const strip_trailing_slash = (route_value) => {
+    if (!route_value) {
+        return '/';
+    }
+
+    let normalized_route = ensure_route_leading_slash(String(route_value));
+    while (normalized_route.length > 1 && normalized_route.endsWith('/')) {
+        normalized_route = normalized_route.slice(0, -1);
+    }
+    return normalized_route;
+};
+
+const normalize_route_path = (route_value, fallback_route = '/') => {
+    const route_candidate = route_value || fallback_route || '/';
+    return strip_trailing_slash(route_candidate);
+};
+
+const normalize_base_path = (base_path) => {
+    if (!base_path) {
+        return '';
+    }
+
+    const normalized_base_path = normalize_route_path(base_path, '/');
+    return normalized_base_path === '/' ? '' : normalized_base_path;
+};
+
 const prepare_webpage_route = (server, route, page_options = {}, defaults = {}) => {
     return new Promise((resolve, reject) => {
         try {
@@ -49,9 +79,14 @@ const prepare_webpage_route = (server, route, page_options = {}, defaults = {})
             webpage_publisher.on('ready', (bundle) => {
                 try {
                     if (bundle && bundle._arr) {
+                        const target_router = server.router || server.server_router;
+                        if (!target_router || typeof target_router.set_route !== 'function') {
+                            reject(new Error(`Server router is unavailable while preparing route ${route}`));
+                            return;
+                        }
                         for (const item of bundle._arr) {
                             const static_responder = new Static_Route_HTTP_Responder(item);
-                            server.router.set_route(item.route, static_responder, static_responder.handle_http);
+                            target_router.set_route(item.route, static_responder, static_responder.handle_http);
                         }
                         resolve();
                         return;
@@ -197,8 +232,404 @@ const normalize_resource_entries = (resources_option) => {
     throw new Error('`resources` must be an object map or an array.');
 };
 
+const is_plain_object = (value) => {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+};
+
+const is_website_like = (value) => {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+
+    if (value[website_marker] === true) {
+        return true;
+    }
+
+    if (value instanceof Website) {
+        return true;
+    }
+
+    const has_pages_collection = value.pages !== undefined || value._pages !== undefined;
+    if (has_pages_collection) {
+        return true;
+    }
+
+    return typeof value.add_page === 'function'
+        && typeof value.get_page === 'function';
+};
+
+const is_webpage_like = (value) => {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+
+    if (value[webpage_marker] === true) {
+        return true;
+    }
+
+    if (value instanceof Webpage) {
+        return true;
+    }
+
+    return typeof value.path === 'string'
+        && (
+            typeof value.ctrl === 'function'
+            || typeof value.Ctrl === 'function'
+            || typeof value.content === 'function'
+        );
+};
+
+const extract_page_ctrl = (page_spec = {}) => {
+    const candidate_ctrl = page_spec.ctrl || page_spec.Ctrl;
+    if (candidate_ctrl !== undefined) {
+        return candidate_ctrl;
+    }
+
+    if (typeof page_spec.content === 'function') {
+        return page_spec.content;
+    }
+
+    return undefined;
+};
+
+const normalize_page_entry = (page_spec = {}, fallback_route = '/') => {
+    const source_spec = typeof page_spec === 'function'
+        ? { ctrl: page_spec }
+        : (is_plain_object(page_spec) ? { ...page_spec } : {});
+
+    const route_value = source_spec.path || source_spec.route || fallback_route || '/';
+    const route = normalize_route_path(route_value, '/');
+
+    const content_ctrl = extract_page_ctrl(source_spec);
+    const normalized_page = {
+        ...source_spec,
+        path: route,
+        route,
+        ctrl: content_ctrl,
+        Ctrl: content_ctrl,
+        content: content_ctrl
+    };
+
+    if (source_spec.content !== undefined && typeof source_spec.content !== 'function') {
+        normalized_page.content_data = source_spec.content;
+    }
+
+    return [route, normalized_page];
+};
+
+const normalize_website_pages = (website_value) => {
+    const normalized_pages = [];
+    const push_page_entry = (page_entry, fallback_route) => {
+        normalized_pages.push(normalize_page_entry(page_entry, fallback_route));
+    };
+
+    if (Array.isArray(website_value.pages)) {
+        for (const page_entry of website_value.pages) {
+            push_page_entry(page_entry, page_entry && page_entry.path ? page_entry.path : '/');
+        }
+        return normalized_pages;
+    }
+
+    if (website_value.pages instanceof Map) {
+        for (const [route_key, page_entry] of website_value.pages.entries()) {
+            push_page_entry(page_entry, route_key);
+        }
+        return normalized_pages;
+    }
+
+    if (website_value.pages && Array.isArray(website_value.pages._arr)) {
+        for (const page_entry of website_value.pages._arr) {
+            push_page_entry(page_entry, page_entry && page_entry.path ? page_entry.path : '/');
+        }
+        return normalized_pages;
+    }
+
+    if (website_value._pages instanceof Map) {
+        for (const [route_key, page_entry] of website_value._pages.entries()) {
+            push_page_entry(page_entry, route_key);
+        }
+        return normalized_pages;
+    }
+
+    if (is_plain_object(website_value.pages)) {
+        for (const [route_key, page_entry] of Object.entries(website_value.pages)) {
+            push_page_entry(page_entry, route_key);
+        }
+    }
+
+    return normalized_pages;
+};
+
+const normalize_endpoint_entry = (endpoint_name, endpoint_value = {}, default_base_path = '') => {
+    const normalized_base_path = normalize_base_path(default_base_path);
+    const resolve_default_endpoint_path = (route_name) => {
+        if (typeof route_name === 'string' && route_name.startsWith('/')) {
+            return join_base_path(normalized_base_path, route_name);
+        }
+        if (typeof route_name === 'string' && route_name.length > 0) {
+            return join_base_path(normalized_base_path, `/api/${route_name}`);
+        }
+        return join_base_path(normalized_base_path, '/api');
+    };
+
+    if (typeof endpoint_value === 'function') {
+        if (typeof endpoint_name !== 'string' || endpoint_name.length === 0) {
+            return null;
+        }
+        return {
+            name: endpoint_name,
+            handler: endpoint_value,
+            method: 'GET',
+            path: resolve_default_endpoint_path(endpoint_name)
+        };
+    }
+
+    if (!is_plain_object(endpoint_value) || typeof endpoint_value.handler !== 'function') {
+        return null;
+    }
+
+    const endpoint_label = endpoint_value.name || endpoint_name;
+    if (!endpoint_value.path && (typeof endpoint_label !== 'string' || endpoint_label.length === 0)) {
+        return null;
+    }
+
+    const endpoint_method = endpoint_value.method || 'GET';
+    const endpoint_path = endpoint_value.path
+        ? normalize_route_path(endpoint_value.path, '/')
+        : resolve_default_endpoint_path(endpoint_label);
+
+    return {
+        name: endpoint_label,
+        handler: endpoint_value.handler,
+        method: endpoint_method,
+        path: endpoint_path,
+        description: endpoint_value.description,
+        // Extended API metadata for OpenAPI / Swagger generation.
+        summary: endpoint_value.summary,
+        tags: endpoint_value.tags,
+        params: endpoint_value.params,
+        returns: endpoint_value.returns,
+        schema: endpoint_value.schema,
+        // Enhancement support: raw handler, deprecated, operationId.
+        raw: endpoint_value.raw,
+        deprecated: endpoint_value.deprecated,
+        operationId: endpoint_value.operationId
+    };
+};
+
+const normalize_website_endpoints = (website_value, normalized_base_path = '') => {
+    const normalized_endpoints = [];
+    const push_endpoint = (endpoint_entry, endpoint_name) => {
+        if (!endpoint_entry) {
+            return;
+        }
+
+        if (typeof endpoint_entry === 'function') {
+            if (typeof endpoint_name !== 'string' || endpoint_name.length === 0) {
+                return;
+            }
+            const normalized_endpoint = normalize_endpoint_entry(endpoint_name, endpoint_entry, normalized_base_path);
+            if (normalized_endpoint) {
+                normalized_endpoints.push(normalized_endpoint);
+            }
+            return;
+        }
+
+        if (is_plain_object(endpoint_entry) && typeof endpoint_entry.handler === 'function') {
+            const normalized_endpoint = normalize_endpoint_entry(
+                endpoint_name || endpoint_entry.name,
+                endpoint_entry,
+                normalized_base_path
+            );
+            if (normalized_endpoint) {
+                normalized_endpoints.push(normalized_endpoint);
+            }
+            return;
+        }
+
+        if (is_plain_object(endpoint_entry) && typeof endpoint_entry.publish === 'function') {
+            const normalized_endpoint = normalize_endpoint_entry(endpoint_name, endpoint_entry.publish, normalized_base_path);
+            if (!normalized_endpoint) {
+                return;
+            }
+            normalized_endpoints.push(normalized_endpoint);
+        }
+    };
+
+    if (Array.isArray(website_value.api_endpoints)) {
+        for (const endpoint_entry of website_value.api_endpoints) {
+            push_endpoint(endpoint_entry, endpoint_entry && endpoint_entry.name);
+        }
+        return normalized_endpoints;
+    }
+
+    if (website_value._api instanceof Map) {
+        for (const [endpoint_name, endpoint_entry] of website_value._api.entries()) {
+            push_endpoint(
+                is_plain_object(endpoint_entry)
+                    ? { name: endpoint_name, ...endpoint_entry }
+                    : endpoint_entry,
+                endpoint_name
+            );
+        }
+        return normalized_endpoints;
+    }
+
+    if (website_value.api && typeof website_value.api[Symbol.iterator] === 'function' && !is_plain_object(website_value.api)) {
+        for (const endpoint_entry of website_value.api) {
+            if (Array.isArray(endpoint_entry)) {
+                const [endpoint_name, endpoint_value] = endpoint_entry;
+                const normalized_endpoint = normalize_endpoint_entry(endpoint_name, endpoint_value, normalized_base_path);
+                if (normalized_endpoint) {
+                    normalized_endpoints.push(normalized_endpoint);
+                }
+            } else {
+                push_endpoint(endpoint_entry, endpoint_entry && endpoint_entry.name);
+            }
+        }
+        return normalized_endpoints;
+    }
+
+    if (is_plain_object(website_value.api)) {
+        for (const [endpoint_name, endpoint_value] of Object.entries(website_value.api)) {
+            const normalized_endpoint = normalize_endpoint_entry(endpoint_name, endpoint_value, normalized_base_path);
+            if (normalized_endpoint) {
+                normalized_endpoints.push(normalized_endpoint);
+            }
+        }
+    }
+
+    return normalized_endpoints;
+};
+
+const join_base_path = (base_path, route_path) => {
+    const normalized_route = normalize_route_path(route_path || '/', '/');
+    const normalized_base = normalize_base_path(base_path);
+
+    if (!normalized_base) {
+        return normalized_route;
+    }
+
+    if (normalized_route === '/') {
+        return normalized_base;
+    }
+
+    return `${normalized_base}${normalized_route}`;
+};
+
+const dedupe_normalized_endpoints = (normalized_endpoints = []) => {
+    const deduped_endpoints = [];
+    const seen_endpoint_keys = new Set();
+
+    for (const endpoint of normalized_endpoints) {
+        if (!endpoint || typeof endpoint.handler !== 'function') {
+            continue;
+        }
+
+        const endpoint_method = String(endpoint.method || 'GET').toUpperCase();
+        const endpoint_path = endpoint.path
+            ? normalize_route_path(endpoint.path, '/')
+            : (
+                typeof endpoint.name === 'string' && endpoint.name.length > 0
+                    ? endpoint.name
+                    : ''
+            );
+        const endpoint_key = `${endpoint_method} ${endpoint_path}`;
+        if (seen_endpoint_keys.has(endpoint_key)) {
+            continue;
+        }
+
+        seen_endpoint_keys.add(endpoint_key);
+        deduped_endpoints.push({
+            ...endpoint,
+            method: endpoint_method,
+            path: endpoint.path ? normalize_route_path(endpoint.path, '/') : endpoint.path
+        });
+    }
+
+    return deduped_endpoints;
+};
+
+const normalize_api_endpoints_from_options = (serve_options = {}, base_path = '') => {
+    const collected_endpoints = [];
+
+    if (Array.isArray(serve_options.api_endpoints)) {
+        collected_endpoints.push(...normalize_website_endpoints({
+            api_endpoints: serve_options.api_endpoints
+        }, base_path));
+    } else if (is_plain_object(serve_options.api_endpoints)) {
+        collected_endpoints.push(...normalize_website_endpoints({
+            api: serve_options.api_endpoints
+        }, base_path));
+    }
+
+    if (serve_options.api && typeof serve_options.api === 'object') {
+        collected_endpoints.push(...normalize_website_endpoints({
+            api: serve_options.api
+        }, base_path));
+    }
+
+    return dedupe_normalized_endpoints(collected_endpoints);
+};
+
+const get_manifest_candidate = (input_value, serve_options = {}) => {
+    const input_manifest = normalize_serve_input(input_value);
+    if (input_manifest) {
+        return input_manifest;
+    }
+
+    if (serve_options && typeof serve_options === 'object') {
+        const explicit_webpage = normalize_serve_input(serve_options.webpage);
+        if (explicit_webpage) {
+            return explicit_webpage;
+        }
+
+        const explicit_website = normalize_serve_input(serve_options.website);
+        if (explicit_website) {
+            return explicit_website;
+        }
+    }
+
+    return null;
+};
+
+const normalize_serve_input = (input_value) => {
+    if (is_webpage_like(input_value)) {
+        const [route, page_config] = normalize_page_entry(input_value, input_value.path || '/');
+        return {
+            source: 'webpage',
+            name: input_value.name,
+            meta: input_value.meta || {},
+            assets: input_value.assets || {},
+            pages: [[route, page_config]],
+            api_endpoints: []
+        };
+    }
+
+    if (is_website_like(input_value)) {
+        const base_path = normalize_base_path(input_value.base_path);
+        const normalized_pages = normalize_website_pages(input_value).map(([route, page_config]) => {
+            const route_with_base = join_base_path(base_path, route);
+            return [route_with_base, { ...page_config, path: route_with_base, route: route_with_base }];
+        });
+
+        const normalized_endpoints = normalize_website_endpoints(input_value, base_path);
+        return {
+            source: 'website',
+            name: input_value.name,
+            meta: input_value.meta || {},
+            assets: input_value.assets || {},
+            base_path: base_path || undefined,
+            pages: normalized_pages,
+            api_endpoints: normalized_endpoints
+        };
+    }
+
+    return null;
+};
+
 module.exports = (Server) => {
-    const serve = function(input, maybe_options, maybe_callback) {
+    const serve = function (input, maybe_options, maybe_callback) {
         let callback = null;
         if (typeof maybe_options === 'function') {
             callback = maybe_options;
@@ -225,6 +656,65 @@ module.exports = (Server) => {
             };
         }
 
+        const has_explicit_page_overrides = !!(
+            maybe_options
+            && typeof maybe_options === 'object'
+            && (
+                maybe_options.page !== undefined
+                || maybe_options.pages !== undefined
+                || maybe_options.ctrl !== undefined
+                || maybe_options.Ctrl !== undefined
+            )
+        );
+
+        const normalized_input_manifest = get_manifest_candidate(input, serve_options);
+        if (normalized_input_manifest) {
+            if (!serve_options.name && normalized_input_manifest.name) {
+                serve_options.name = normalized_input_manifest.name;
+            }
+
+            if (
+                !has_explicit_page_overrides
+                && !serve_options.page
+                && Array.isArray(normalized_input_manifest.pages)
+                && normalized_input_manifest.pages.length
+            ) {
+                const normalized_pages_map = {};
+                const seen_routes = new Set();
+                for (const [route, page_config] of normalized_input_manifest.pages) {
+                    const normalized_route = normalize_route_path(route, '/');
+                    if (seen_routes.has(normalized_route)) {
+                        throw new Error(`duplicate_route: ${normalized_route}`);
+                    }
+                    seen_routes.add(normalized_route);
+                    normalized_pages_map[normalized_route] = page_config || {};
+                }
+                serve_options.pages = normalized_pages_map;
+
+                if (
+                    normalized_input_manifest.source === 'webpage'
+                    || normalized_input_manifest.source === 'website'
+                ) {
+                    delete serve_options.ctrl;
+                    delete serve_options.Ctrl;
+                }
+            }
+
+            if (
+                !serve_options.api
+                && !serve_options.api_endpoints
+                && Array.isArray(normalized_input_manifest.api_endpoints)
+                && normalized_input_manifest.api_endpoints.length
+            ) {
+                serve_options.api_endpoints = normalized_input_manifest.api_endpoints;
+            }
+        }
+
+        const manifest_base_path = normalize_base_path(
+            (normalized_input_manifest && normalized_input_manifest.base_path)
+            || serve_options.base_path
+        );
+
         const caller_file = serve_options.caller_file || serve_options.callerFile || guess_caller_file();
         const caller_dir = serve_options.root
             ? lib_path.resolve(process.cwd(), serve_options.root)
@@ -234,29 +724,47 @@ module.exports = (Server) => {
         if (!serve_options.ctrl && serve_options.page) {
             const page_config = serve_options.page;
             serve_options.ctrl = page_config.content || page_config.ctrl || page_config.Ctrl;
-            serve_options.page_route = ensure_route_leading_slash(page_config.route || '/');
+            serve_options.page_route = normalize_route_path(page_config.route || page_config.path || '/', '/');
             serve_options.page_config = page_config;
         }
 
         let additional_pages = [];
+        let use_manual_page_publication = false;
+        if (!serve_options.ctrl && Array.isArray(serve_options.pages)) {
+            throw new Error('`pages` option must be an object map of route -> page config.');
+        }
+
         if (!serve_options.ctrl && serve_options.pages && typeof serve_options.pages === 'object') {
             const page_entries = Object.entries(serve_options.pages);
             if (!page_entries.length) {
                 throw new Error('`pages` option requires at least one entry.');
             }
 
-            const normalized_pages = page_entries.map(([route, cfg]) => [ensure_route_leading_slash(route), cfg || {}]);
-            const root_entry = normalized_pages.find(([route]) => route === '/') || normalized_pages[0];
-            serve_options.ctrl = (root_entry[1].content || root_entry[1].ctrl || root_entry[1].Ctrl);
-            serve_options.page_route = root_entry[0];
-            serve_options.page_config = root_entry[1];
-            additional_pages = normalized_pages.filter(([route]) => route !== serve_options.page_route);
+            const normalized_pages = page_entries.map(([route, cfg]) => [normalize_route_path(route, '/'), cfg || {}]);
+            const seen_page_routes = new Set();
+            for (const [route] of normalized_pages) {
+                if (seen_page_routes.has(route)) {
+                    throw new Error(`duplicate_route: ${route}`);
+                }
+                seen_page_routes.add(route);
+            }
+
+            const root_entry = normalized_pages.find(([route]) => route === '/');
+            if (root_entry) {
+                serve_options.ctrl = (root_entry[1].content || root_entry[1].ctrl || root_entry[1].Ctrl);
+                serve_options.page_route = root_entry[0];
+                serve_options.page_config = root_entry[1];
+                additional_pages = normalized_pages.filter(([route]) => route !== serve_options.page_route);
+            } else {
+                use_manual_page_publication = true;
+                additional_pages = normalized_pages;
+            }
         }
 
         const explicit_client_path = serve_options.clientPath || serve_options.client_path || serve_options.src_path_client_js || serve_options.disk_path_client_js;
         const root_client_path = find_default_client_path(explicit_client_path, caller_dir);
 
-        if (typeof serve_options.ctrl !== 'function' && root_client_path) {
+        if (typeof serve_options.ctrl !== 'function' && root_client_path && !use_manual_page_publication) {
             const auto_ctrl = load_default_control_from_client(root_client_path);
             if (typeof auto_ctrl === 'function') {
                 serve_options.ctrl = auto_ctrl;
@@ -266,10 +774,22 @@ module.exports = (Server) => {
         if (serve_options.page_config && typeof serve_options.ctrl !== 'function') {
             throw new Error('`page` option requires a control constructor.');
         }
-        if (additional_pages.length && typeof serve_options.ctrl !== 'function') {
+        if (additional_pages.length && !use_manual_page_publication && typeof serve_options.ctrl !== 'function') {
             throw new Error('`pages` option requires at least one control constructor.');
         }
 
+        if (use_manual_page_publication) {
+            const invalid_page_entry = additional_pages.find(([, cfg]) => {
+                const page_ctrl = cfg && (cfg.content || cfg.ctrl || cfg.Ctrl);
+                return typeof page_ctrl !== 'function';
+            });
+            if (invalid_page_entry) {
+                throw new Error(`Page at route "${invalid_page_entry[0]}" requires a control constructor as content.`);
+            }
+        }
+
+        const normalized_api_endpoints = normalize_api_endpoints_from_options(serve_options, manifest_base_path);
+
         const port = Number.isFinite(serve_options.port)
             ? Number(serve_options.port)
             : (serve_options.port === 'auto' ? 0 : (process.env.PORT ? Number(process.env.PORT) : 8080));
@@ -293,7 +813,11 @@ module.exports = (Server) => {
 
         if (typeof serve_options.ctrl === 'function') {
             server_spec.Ctrl = serve_options.ctrl;
-        } else if (serve_options.api && typeof serve_options.api === 'object') {
+        } else if (
+            (serve_options.api && typeof serve_options.api === 'object')
+            || normalized_api_endpoints.length
+            || use_manual_page_publication
+        ) {
             server_spec.website = false;
         }
 
@@ -383,6 +907,85 @@ module.exports = (Server) => {
             ? Number(serve_options.readyTimeoutMs)
             : 120000;
 
+        const manifest_page_entries = [];
+        const seen_manifest_routes = new Set();
+        const push_manifest_page = (route, page_config = {}) => {
+            const normalized_route = normalize_route_path(route, '/');
+            if (seen_manifest_routes.has(normalized_route)) {
+                return;
+            }
+            seen_manifest_routes.add(normalized_route);
+            manifest_page_entries.push([normalized_route, page_config || {}]);
+        };
+
+        if (normalized_input_manifest && Array.isArray(normalized_input_manifest.pages) && normalized_input_manifest.pages.length) {
+            for (const [route, page_config] of normalized_input_manifest.pages) {
+                push_manifest_page(route, page_config);
+            }
+        } else {
+            if (serve_options.page_config && serve_options.page_route) {
+                push_manifest_page(serve_options.page_route, serve_options.page_config);
+            }
+            for (const [route, page_config] of additional_pages) {
+                push_manifest_page(route, page_config);
+            }
+            if (!manifest_page_entries.length && typeof serve_options.ctrl === 'function' && !use_manual_page_publication) {
+                push_manifest_page('/', {
+                    ctrl: serve_options.ctrl,
+                    content: serve_options.ctrl,
+                    name: serve_options.name
+                });
+            }
+        }
+
+        const manifest_warning_messages = [];
+        const non_get_endpoints = normalized_api_endpoints.filter((endpoint) => endpoint.method !== 'GET');
+        if (non_get_endpoints.length) {
+            manifest_warning_messages.push(
+                'API endpoint metadata includes non-GET methods, but server.publish currently treats handlers as method-agnostic.'
+            );
+        }
+
+        const effective_website_manifest = {
+            source: (normalized_input_manifest && normalized_input_manifest.source)
+                || (use_manual_page_publication ? 'pages' : (typeof serve_options.ctrl === 'function' ? 'ctrl' : 'legacy')),
+            name: serve_options.name || server_spec.name || 'jsgui3 server',
+            base_path: manifest_base_path || undefined,
+            meta: (normalized_input_manifest && normalized_input_manifest.meta) || serve_options.meta || {},
+            assets: (normalized_input_manifest && normalized_input_manifest.assets) || serve_options.assets || {},
+            pages: manifest_page_entries.map(([route, page_config]) => {
+                const page_ctrl = extract_page_ctrl(page_config || {});
+                return {
+                    route,
+                    path: route,
+                    name: page_config ? page_config.name : undefined,
+                    title: page_config ? page_config.title : undefined,
+                    render_mode: (page_config && page_config.render_mode)
+                        || (typeof page_ctrl === 'function' ? 'dynamic' : 'static'),
+                    has_ctrl: typeof page_ctrl === 'function'
+                };
+            }),
+            api_endpoints: normalized_api_endpoints.map((endpoint) => ({
+                name: endpoint.name,
+                method: endpoint.method || 'GET',
+                path: endpoint.path,
+                description: endpoint.description,
+                summary: endpoint.summary,
+                tags: endpoint.tags,
+                params: endpoint.params,
+                returns: endpoint.returns,
+                schema: endpoint.schema
+            }))
+        };
+
+        server_instance.website_manifest = effective_website_manifest;
+        server_instance.publication_summary = {
+            source: effective_website_manifest.source,
+            page_routes: effective_website_manifest.pages.map((page) => page.path),
+            api_routes: effective_website_manifest.api_endpoints.map((endpoint) => `${endpoint.method} ${endpoint.path}`),
+            warnings: manifest_warning_messages
+        };
+
         const extra_page_promises = additional_pages.map(([route, cfg]) => prepare_webpage_route(server_instance, route, cfg, {
             caller_dir,
             debug: debug_enabled,
@@ -399,14 +1002,114 @@ module.exports = (Server) => {
             }));
         }
 
-        if (serve_options.api && typeof serve_options.api === 'object') {
-            for (const [name, handler] of Object.entries(serve_options.api)) {
-                if (typeof handler === 'function') {
-                    server_instance.publish(name, handler);
+        // ── Register middleware ──────────────────────────────
+        // `middleware` accepts an array of (req, res, next) functions.
+        if (Array.isArray(serve_options.middleware)) {
+            for (const mw of serve_options.middleware) {
+                if (typeof mw === 'function') {
+                    server_instance.use(mw);
                 }
             }
         }
 
+        for (const endpoint of normalized_api_endpoints) {
+            if (!endpoint || typeof endpoint.handler !== 'function') {
+                continue;
+            }
+
+            const endpoint_route = endpoint.path || endpoint.name;
+            if (typeof endpoint_route !== 'string' || endpoint_route.length === 0) {
+                continue;
+            }
+
+            const publish_meta = { method: endpoint.method };
+            if (endpoint.summary) publish_meta.summary = endpoint.summary;
+            if (endpoint.description) publish_meta.description = endpoint.description;
+            if (endpoint.tags) publish_meta.tags = endpoint.tags;
+            if (endpoint.params) publish_meta.params = endpoint.params;
+            if (endpoint.returns) publish_meta.returns = endpoint.returns;
+            if (endpoint.deprecated) publish_meta.deprecated = endpoint.deprecated;
+            if (endpoint.operationId) publish_meta.operationId = endpoint.operationId;
+            if (endpoint.raw) publish_meta.raw = endpoint.raw;
+            server_instance.publish(endpoint.path || endpoint.name, endpoint.handler, publish_meta);
+        }
+        // ── Data query endpoints ──────────────────────────────
+        // `data` accepts an object map of name → {query_fn, adapter, schema}.
+        // Each entry creates a Query_Resource + Query_Publisher at /api/data/<name>.
+        let data_endpoint_count = 0;
+        if (serve_options.data && typeof serve_options.data === 'object') {
+            const Query_Publisher = require('./publishers/query-publisher');
+            const Query_Resource = require('./resources/query-resource');
+            const Array_Adapter = require('./resources/adapters/array-adapter');
+
+            for (const [data_name, data_spec] of Object.entries(serve_options.data)) {
+                if (!data_spec) continue;
+
+                let query_fn;
+                let resource = null;
+
+                if (typeof data_spec.query_fn === 'function') {
+                    query_fn = data_spec.query_fn;
+                } else if (data_spec.adapter && typeof data_spec.adapter.query === 'function') {
+                    resource = new Query_Resource({
+                        name: data_name,
+                        adapter: data_spec.adapter,
+                        schema: data_spec.schema
+                    });
+                    query_fn = (params) => resource.query(params);
+                } else if (Array.isArray(data_spec.data)) {
+                    const adapter = new Array_Adapter({ data: data_spec.data });
+                    resource = new Query_Resource({
+                        name: data_name,
+                        adapter,
+                        schema: data_spec.schema
+                    });
+                    query_fn = (params) => resource.query(params);
+                } else {
+                    continue;
+                }
+
+                if (resource) {
+                    configured_resources.push(resource);
+                    if (!server_instance.configured_resources) {
+                        server_instance.configured_resources = configured_resources;
+                    }
+                }
+
+                const data_route = ensure_route_leading_slash(`/api/data/${data_name}`);
+                const publisher = new Query_Publisher({
+                    name: data_name,
+                    query_fn,
+                    schema: data_spec.schema
+                });
+                server_instance.server_router.set_route(data_route, publisher, publisher.handle_http);
+                data_endpoint_count++;
+            }
+        }
+
+        // ── Swagger / OpenAPI auto-registration ──────────────
+        // swagger: true   → always enable
+        // swagger: false  → always disable
+        // swagger: omitted → enable in non-production
+        const swagger_option = serve_options.swagger;
+        const swagger_enabled = swagger_option === true
+            || (swagger_option !== false && process.env.NODE_ENV !== 'production');
+
+        if (swagger_enabled) {
+            const swagger_options = typeof swagger_option === 'object' ? swagger_option : {};
+            server_instance._register_swagger_routes({
+                title: swagger_options.title || serve_options.name,
+                version: swagger_options.version,
+                description: swagger_options.description
+            });
+        }
+
+        const should_force_ready = !serve_options.ctrl && (
+            normalized_api_endpoints.length > 0
+            || data_endpoint_count > 0
+            || use_manual_page_publication
+        );
+
         return new Promise((resolve, reject) => {
             let has_started = false;
             let has_settled = false;
@@ -448,6 +1151,13 @@ module.exports = (Server) => {
 
                 server_instance.port = actual_port;
 
+                const start_options = {
+                    ...(serve_options.start && typeof serve_options.start === 'object' ? serve_options.start : {})
+                };
+                if (typeof serve_options.on_port_conflict === 'string' && !start_options.on_port_conflict) {
+                    start_options.on_port_conflict = serve_options.on_port_conflict;
+                }
+
                 server_instance.start(actual_port, (error) => {
                     if (error) {
                         return settle(reject, error);
@@ -458,7 +1168,7 @@ module.exports = (Server) => {
                     }).catch((resource_error) => {
                         settle(reject, resource_error);
                     });
-                });
+                }, start_options);
             };
 
             server_instance.on('ready', () => {
@@ -476,7 +1186,7 @@ module.exports = (Server) => {
                 });
             });
 
-            if (serve_options.api && typeof serve_options.api === 'object' && !serve_options.ctrl) {
+            if (should_force_ready) {
                 server_instance.raise('ready');
             }