@ecopages/core 0.2.0-alpha.9 → 0.2.1

package/src/eco/eco.ts

@@ -1,242 +0,0 @@
-/**
- * The eco namespace - unified component and page factory API
- * @module
- */
-
-import type {
-	EcoComponent,
-	EcoHtmlComponent,
-	EcoLayoutComponent,
-	EcoPagesElement,
-	EcoPageComponent,
-	GetMetadata,
-	GetStaticPaths,
-	GetStaticProps,
-	Middleware,
-	RequestLocals,
-	RequestPageContext,
-} from '../public-types.ts';
-import type { CacheStrategy } from '../services/cache/cache.types.ts';
-import type {
-	ComponentOptions,
-	Eco,
-	HtmlOptions,
-	LayoutOptions,
-	PageOptions,
-	PageOptionsBase,
-	PagePropsFor,
-	PagePropsForWithLocals,
-	PageRequires,
-} from './eco.types.ts';
-import { createNodeId, createPropsRef, createSlotRef, getComponentRenderContext } from './component-render-context.ts';
-import { createComponentMarker, parseComponentMarkers } from '../route-renderer/component-graph/component-marker.ts';
-import { getComponentReference } from '../route-renderer/component-graph/component-reference.ts';
-import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from './eco.utils.ts';
-
-/**
- * Creates a component factory with lazy-trigger support and deferred-boundary
- * marker emission.
- *
- * Behavior:
- * - In normal render flow, returns `options.render(props)` with optional lazy
- *   trigger/script wrapping.
- * - When rendering under component graph context and the active boundary policy
- *   decides the target boundary should defer, emits an `eco-marker` token
- *   instead of rendering the component immediately.
- *
- * @param options Component options for rendering and dependency declaration.
- * @returns Configured eco component.
- */
-function createComponentFactory<P, E>(options: ComponentOptions<P, E>): EcoComponent<P, E> {
-	const integrationName = options.integration ?? options.__eco?.integration;
-	const comp: EcoComponent<P, E> = ((props: P) => {
-		const renderContext = getComponentRenderContext();
-		const shouldEmitMarker =
-			renderContext !== undefined &&
-			renderContext.boundaryContext.decideBoundaryRender({
-				currentIntegration: renderContext.currentIntegration,
-				targetIntegration: integrationName,
-				component: comp,
-			}) === 'defer';
-
-		if (shouldEmitMarker && renderContext) {
-			const nodeId = createNodeId(renderContext);
-			const propsRef = createPropsRef(renderContext);
-			const componentRef = getComponentReference(comp);
-
-			const componentProps = (props ?? {}) as Record<string, unknown>;
-			renderContext.propsByRef[propsRef] = componentProps;
-
-			let slotRef: string | undefined;
-			const children = componentProps.children;
-			if (typeof children === 'string' && children.includes('<eco-marker')) {
-				const childMarkers = parseComponentMarkers(children);
-				if (childMarkers.length > 0) {
-					slotRef = createSlotRef(renderContext);
-					renderContext.slotChildrenByRef[slotRef] = childMarkers.map((marker) => marker.nodeId);
-				}
-			}
-
-			return createComponentMarker({
-				nodeId,
-				integration: integrationName as string,
-				componentRef,
-				propsRef,
-				slotRef,
-			}) as E;
-		}
-
-		const content = options.render(props);
-
-		const lazyTriggers = comp.config?._resolvedLazyTriggers;
-		if (lazyTriggers && lazyTriggers.length > 0) {
-			const triggerId = lazyTriggers[0].triggerId;
-			if (isThenable(content)) {
-				return content.then((resolvedContent) => addTriggerAttribute(resolvedContent, triggerId));
-			}
-			return addTriggerAttribute(content, triggerId);
-		}
-
-		const lazyGroups = comp.config?._resolvedLazyScripts;
-
-		if (lazyGroups && lazyGroups.length > 0) {
-			if (isThenable(content)) {
-				return content.then((resolvedContent) => wrapWithScriptsInjector(resolvedContent, lazyGroups));
-			}
-			return wrapWithScriptsInjector(content, lazyGroups);
-		}
-
-		return content;
-	}) as EcoComponent<P, E>;
-
-	comp.config = {
-		__eco: options.__eco,
-		integration: options.integration,
-		dependencies: options.dependencies,
-	};
-
-	return comp;
-}
-
-/**
- * Creates a reusable component with optional dependencies.
- *
- * @param options Component definition options.
- * @returns Eco component function.
- */
-function component<P = {}, E = EcoPagesElement>(options: ComponentOptions<P, E>): EcoComponent<P, E> {
-	return createComponentFactory(options);
-}
-
-/**
- * Creates a document shell component.
- *
- * Phase 1 keeps this as a semantic alias over eco.component() so existing
- * renderer behavior remains unchanged.
- */
-function html<E = EcoPagesElement>(options: HtmlOptions<E>): EcoHtmlComponent<E> {
-	return createComponentFactory(options) as EcoHtmlComponent<E>;
-}
-
-/**
- * Creates a route layout component.
- *
- * Phase 1 keeps this as a semantic alias over eco.component() so existing
- * renderer behavior remains unchanged.
- */
-function layout<E = EcoPagesElement>(options: LayoutOptions<E>): EcoLayoutComponent<E> {
-	return createComponentFactory(options) as EcoLayoutComponent<E>;
-}
-
-/**
- * Creates a page component with typed props and optional static helpers.
- */
-function page<T = {}, E = EcoPagesElement>(options: PageOptions<T, E> & { requires?: undefined }): EcoPageComponent<T>;
-function page<T = {}, E = EcoPagesElement, const K extends keyof RequestLocals = keyof RequestLocals>(
-	options: Omit<PageOptions<T, E>, 'render' | 'requires'> & {
-		requires: PageRequires<K>;
-		render: (props: PagePropsForWithLocals<T, K>) => E | Promise<E>;
-	},
-): EcoPageComponent<T>;
-
-/**
- * Creates a page component and attaches optional static APIs.
- *
- * @param options Page options.
- * @returns Eco page component.
- */
-function page<T, E>(
-	options: PageOptionsBase<T, E> & { cache?: CacheStrategy; middleware?: Middleware[] },
-): EcoPageComponent<T> {
-	const { layout, dependencies, render, staticPaths, staticProps, metadata, cache, requires, middleware } = options;
-
-	const componentOptions: ComponentOptions<PagePropsFor<T> & Partial<RequestPageContext>, E> = {
-		__eco: options.__eco,
-		integration: options.integration,
-		dependencies: layout
-			? {
-					...dependencies,
-					components: [...(dependencies?.components || []), layout],
-				}
-			: dependencies,
-		render,
-	};
-
-	const pageComponent = createComponentFactory(componentOptions) as EcoPageComponent<T>;
-
-	if (layout && pageComponent.config) {
-		pageComponent.config.layout = layout;
-	}
-
-	if (staticPaths) pageComponent.staticPaths = staticPaths;
-	if (staticProps) pageComponent.staticProps = staticProps;
-	if (metadata) pageComponent.metadata = metadata;
-	if (cache) pageComponent.cache = cache;
-	if (requires) pageComponent.requires = requires;
-	if (middleware) pageComponent.middleware = middleware;
-
-	return pageComponent;
-}
-
-/**
- * Type-safe wrapper for metadata functions.
- *
- * @param fn Metadata factory function.
- * @returns The same function.
- */
-function metadata<P = {}>(fn: GetMetadata<P>): GetMetadata<P> {
-	return fn;
-}
-
-/**
- * Type-safe wrapper for static paths functions.
- *
- * @param fn Static paths function.
- * @returns The same function.
- */
-function staticPaths(fn: GetStaticPaths): GetStaticPaths {
-	return fn;
-}
-
-/**
- * Type-safe wrapper for static props functions.
- *
- * @param fn Static props function.
- * @returns The same function.
- */
-function staticProps<P>(fn: GetStaticProps<P>): GetStaticProps<P> {
-	return fn;
-}
-
-/**
- * The eco namespace - provides factories for components and pages
- */
-export const eco: Eco = {
-	component,
-	html,
-	layout,
-	page,
-	metadata,
-	staticPaths,
-	staticProps,
-};

package/src/eco/eco.types.ts

@@ -1,221 +0,0 @@
-/**
- * Type definitions for the eco namespace API
- * @module
- */
-
-import type {
-	DependencyLazyTrigger,
-	EcoComponent,
-	EcoComponentDependencies,
-	EcoHtmlComponent,
-	EcoInjectedMeta,
-	EcoLayoutComponent,
-	EcoPageLayoutComponent,
-	EcoPagesElement,
-	GetMetadata,
-	GetStaticPaths,
-	GetStaticProps,
-	HtmlTemplateProps,
-	LayoutProps,
-	Middleware,
-	RequestLocals,
-	RequestPageContext,
-} from '../public-types.ts';
-import type { CacheStrategy } from '../services/cache/cache.types.ts';
-
-type WithRequiredLocals<K extends keyof RequestLocals> = Omit<RequestLocals, K> & {
-	[P in K]-?: Exclude<RequestLocals[P], null | undefined>;
-};
-
-type RequiresKeys = keyof RequestLocals;
-
-export type PageRequires<K extends RequiresKeys = RequiresKeys> = K | readonly K[];
-
-/**
- * Lazy trigger options map directly to scripts-injector attributes.
- * Only one trigger type can be active at a time.
- */
-export type LazyTrigger = DependencyLazyTrigger;
-
-/**
- * Options for creating a component with eco.component()
- * @template P - The props type for the component
- * @template E - The element/return type (defaults to EcoPagesElement for Kita, use ReactNode for React)
- */
-export interface ComponentOptions<P, E = EcoPagesElement> {
-	/** @internal Injected by eco-component-meta-plugin */
-	__eco?: EcoInjectedMeta;
-	integration?: string;
-	dependencies?: EcoComponentDependencies;
-	render: (props: P) => E | Promise<E>;
-}
-
-export type HtmlOptions<E = EcoPagesElement> = ComponentOptions<HtmlTemplateProps, E>;
-
-export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E>;
-
-/**
- * Base options shared by all page variants
- */
-export interface PageOptionsBase<T, E = EcoPagesElement> {
-	/** @internal Injected by eco-component-meta-plugin */
-	__eco?: EcoInjectedMeta;
-	integration?: string;
-	dependencies?: EcoComponentDependencies;
-	layout?: EcoPageLayoutComponent<E>;
-
-	/**
-	 * Define static paths for dynamic routes (e.g., [slug].tsx).
-	 * Returns all possible paths that should be pre-rendered at build time.
-	 */
-	staticPaths?: GetStaticPaths;
-
-	/**
-	 * Fetch data for the page at build time.
-	 * Props returned here are passed to both render() and metadata().
-	 */
-	staticProps?: GetStaticProps<T>;
-
-	/**
-	 * Generate page metadata (title, description, etc.).
-	 * Receives props from staticProps if defined.
-	 */
-	metadata?: GetMetadata<T>;
-
-	/**
-	 * Declares which `locals` keys must be present for this page.
-	 *
-	 * This is a typing and documentation feature; runtime enforcement must be done via handler/page middleware.
-	 */
-	requires?: PageRequires;
-
-	render: (props: PagePropsFor<T> & Partial<RequestPageContext>) => E | Promise<E>;
-}
-
-/**
- * Page options without middleware - allows any cache strategy
- */
-interface PageOptionsWithoutMiddleware<T, E = EcoPagesElement> extends PageOptionsBase<T, E> {
-	/**
-	 * Cache configuration for ISR (Incremental Static Regeneration).
-	 * - `'static'`: Cache indefinitely (default)
-	 * - `'dynamic'`: No caching, render on every request
-	 * - `{ revalidate: number, tags?: string[] }`: Cache with time-based revalidation
-	 */
-	cache?: CacheStrategy;
-	middleware?: undefined;
-}
-
-/**
- * Page options with middleware - requires cache: 'dynamic'
- */
-interface PageOptionsWithMiddleware<T, E = EcoPagesElement> extends PageOptionsBase<T, E> {
-	/**
-	 * Cache must be 'dynamic' when using middleware.
-	 * Middleware runs on every request, so caching would bypass middleware effects.
-	 */
-	cache: 'dynamic';
-	/**
-	 * Request-time middleware for file-based routes.
-	 * Runs before rendering and can short-circuit by returning a Response.
-	 */
-	middleware: Middleware[];
-}
-
-/**
- * Options for creating a page with eco.page()
- *
- * Supports two patterns:
- * 1. **Consolidated API** (recommended): Define staticPaths, staticProps, and metadata inline
- * 2. **Separate exports** (legacy): Export getStaticPaths, getStaticProps, getMetadata separately
- *
- * When using `middleware`, `cache` must be set to `'dynamic'` because middleware
- * runs on every request and caching would bypass middleware effects.
- *
- * @template T - The props type for the page
- * @template E - The element/return type (defaults to EcoPagesElement for Kita, use ReactNode for React)
- */
-export type PageOptions<T, E = EcoPagesElement> = PageOptionsWithoutMiddleware<T, E> | PageOptionsWithMiddleware<T, E>;
-
-export type PagePropsForWithLocals<T, K extends RequiresKeys | never = never> = PagePropsFor<T> &
-	(K extends never
-		? Partial<RequestPageContext>
-		: Omit<Partial<RequestPageContext>, 'locals'> & {
-				locals: WithRequiredLocals<Extract<K, keyof RequestLocals>>;
-			});
-
-/**
- * Extracts props type from getStaticProps return type, or uses T directly if it's a props object.
- * Always includes params and query for page context.
- */
-export type PagePropsFor<T> =
-	T extends GetStaticProps<infer P>
-		? P & { params?: Record<string, string>; query?: Record<string, string> }
-		: T & { params?: Record<string, string>; query?: Record<string, string> };
-
-/**
- * A page component with optional attached static functions.
- * Used by the consolidated eco.page() API where staticPaths, staticProps,
- * and metadata are defined inline and attached to the component.
- */
-export type EcoPageComponent<T> = EcoComponent<PagePropsFor<T> & Partial<RequestPageContext>> & {
-	staticPaths?: GetStaticPaths;
-	staticProps?: GetStaticProps<T>;
-	metadata?: GetMetadata<T>;
-	cache?: CacheStrategy;
-	requires?: PageRequires;
-	middleware?: Middleware[];
-};
-
-/**
- * The eco namespace interface
- */
-export interface Eco {
-	/**
-	 * Create a reusable component with dependencies and optional lazy-loading.
-	 * @template P - Props type
-	 * @template E - Element/return type (EcoPagesElement for Kita, ReactNode for React)
-	 */
-	component: <P = {}, E = EcoPagesElement>(options: ComponentOptions<P, E>) => EcoComponent<P, E>;
-
-	/**
-	 * Create a document shell component for the HTML wrapper.
-	 */
-	html: <E = EcoPagesElement>(options: HtmlOptions<E>) => EcoHtmlComponent<E>;
-
-	/**
-	 * Create a route layout component.
-	 */
-	layout: <E = EcoPagesElement>(options: LayoutOptions<E>) => EcoLayoutComponent<E>;
-
-	/**
-	 * Create a page component with type-safe props from getStaticProps.
-	 * Returns an EcoPageComponent with attached staticPaths, staticProps, and metadata.
-	 *
-	 * If `requires` is provided, the `render` callback receives `locals` as required and non-null for the required keys.
-	 */
-	page: {
-		<T = {}, E = EcoPagesElement>(options: PageOptions<T, E> & { requires?: undefined }): EcoPageComponent<T>;
-		<T = {}, E = EcoPagesElement, const K extends RequiresKeys = RequiresKeys>(
-			options: Omit<PageOptions<T, E>, 'render' | 'requires'> & {
-				requires: PageRequires<K>;
-				render: (props: PagePropsForWithLocals<T, K>) => E | Promise<E>;
-			},
-		): EcoPageComponent<T>;
-	};
-
-	/**
-	 * Type-safe wrapper for page metadata (identity function)
-	 */
-	metadata: <P = {}>(fn: GetMetadata<P>) => GetMetadata<P>;
-
-	/**
-	 * Type-safe wrapper for static paths (identity function)
-	 */
-	staticPaths: (fn: GetStaticPaths) => GetStaticPaths;
-
-	/**
-	 * Type-safe wrapper for static props (identity function)
-	 */
-	staticProps: <P>(fn: GetStaticProps<P>) => GetStaticProps<P>;
-}

package/src/eco/global-injector-map.ts

@@ -1,112 +0,0 @@
-import type { ResolvedLazyTrigger } from '../public-types.ts';
-
-type GlobalInjectorEntry = {
-	'on:idle'?: { scripts: string[] };
-	'on:interaction'?: { value: string; scripts: string[] };
-	'on:visible'?: { value?: string; scripts: string[] };
-};
-
-type GlobalInjectorMap = Record<string, GlobalInjectorEntry>;
-
-/**
- * Converts a flat list of resolved triggers into the map structure consumed
- * by the `initGlobalInjector` bootstrap. Multiple triggers sharing the same
- * `triggerId` are merged so their script lists are deduplicated.
- */
-function buildGlobalInjectorMap(triggers: ResolvedLazyTrigger[]): GlobalInjectorMap {
-	const map: GlobalInjectorMap = {};
-
-	for (const { triggerId, rules } of triggers) {
-		const entry: GlobalInjectorEntry = map[triggerId] ?? {};
-
-		for (const rule of rules) {
-			if ('on:idle' in rule) {
-				const { scripts } = rule['on:idle'];
-				entry['on:idle'] = {
-					scripts: Array.from(new Set([...(entry['on:idle']?.scripts ?? []), ...scripts])),
-				};
-				continue;
-			}
-
-			if ('on:interaction' in rule) {
-				const { value, scripts } = rule['on:interaction'];
-				entry['on:interaction'] = {
-					value,
-					scripts: Array.from(new Set([...(entry['on:interaction']?.scripts ?? []), ...scripts])),
-				};
-				continue;
-			}
-
-			if ('on:visible' in rule) {
-				const { value, scripts } = rule['on:visible'];
-				entry['on:visible'] = {
-					...(value ? { value } : {}),
-					scripts: Array.from(new Set([...(entry['on:visible']?.scripts ?? []), ...scripts])),
-				};
-				continue;
-			}
-		}
-
-		if (Object.keys(entry).length > 0) {
-			map[triggerId] = entry;
-		}
-	}
-
-	return map;
-}
-
-/**
- * Serializes resolved lazy triggers into a JSON string safe for embedding
- * inside an inline `<script type="ecopages/global-injector-map">` tag.
- *
- * The `</script` sequence is escaped because an unescaped occurrence in inline
- * script content causes the HTML parser to close the script tag prematurely,
- * breaking page rendering. `JSON.stringify` does not perform this escape by
- * default, so a targeted replacement is applied after serialization.
- */
-export function buildGlobalInjectorMapScript(triggers: ResolvedLazyTrigger[]): string {
-	const map = buildGlobalInjectorMap(triggers);
-	return JSON.stringify(map).replace(/<\/script/gi, '<\\/script');
-}
-
-/**
- * Builds the inline module script that boots the global lazy injector on the client.
- * Emitted once per page alongside the `ecopages/global-injector-map` script block.
- */
-export function buildGlobalInjectorBootstrapContent(globalInjectorModuleUrl: string): string {
-	return `import { initGlobalInjector } from ${JSON.stringify(globalInjectorModuleUrl)};
-
-function pruneStaleTriggerMaps() {
-	const mapScripts = Array.from(document.querySelectorAll('script[type="ecopages/global-injector-map"]'));
-	if (mapScripts.length <= 1) {
-		return;
-	}
-
-	const latestMapScript = mapScripts[mapScripts.length - 1];
-	for (const mapScript of mapScripts) {
-		if (mapScript !== latestMapScript) {
-			mapScript.remove();
-		}
-	}
-}
-
-const globalScope = window;
-if (typeof globalScope.__ecoGlobalInjectorCleanup === 'function') {
-	globalScope.__ecoGlobalInjectorCleanup();
-}
-
-const injector = initGlobalInjector();
-
-const handleAfterSwap = () => {
-	pruneStaleTriggerMaps();
-	injector.refresh();
-};
-
-document.addEventListener('eco:after-swap', handleAfterSwap);
-pruneStaleTriggerMaps();
-
-globalScope.__ecoGlobalInjectorCleanup = () => {
-	document.removeEventListener('eco:after-swap', handleAfterSwap);
-	injector.cleanup();
-};`;
-}

package/src/eco/lazy-injector-map.ts

@@ -1,120 +0,0 @@
-import type { InjectorMapConfig } from '@ecopages/scripts-injector/types';
-import type { ResolvedLazyScriptGroup } from '../public-types.ts';
-
-/**
- * Normalizes a comma-separated scripts string into absolute script URLs.
- *
- * @param scripts Comma-separated script paths.
- * @returns Normalized script path list.
- */
-function normalizeScripts(scripts: string): string[] {
-	return scripts
-		.split(',')
-		.map((scriptPath) => scriptPath.trim())
-		.filter(Boolean)
-		.map((scriptPath) => {
-			if (scriptPath.startsWith('/')) {
-				return scriptPath;
-			}
-
-			const normalizedRelativePath = scriptPath.replace(/^\/+/, '').replace(/^(\.\/)+/, '');
-			return `/${normalizedRelativePath}`;
-		});
-}
-
-/**
- * Deduplicates comma-separated values while preserving first-seen order.
- *
- * @param values CSV value list.
- * @returns A single normalized CSV string.
- */
-function dedupeCsvValues(values: string[]): string {
-	const seen = new Set<string>();
-
-	for (const value of values) {
-		for (const token of value
-			.split(',')
-			.map((part) => part.trim())
-			.filter(Boolean)) {
-			seen.add(token);
-		}
-	}
-
-	return Array.from(seen).join(',');
-}
-
-/**
- * Builds a scripts-injector map config from resolved lazy script groups.
- *
- * @param lazyGroups Lazy script groups resolved during dependency processing.
- * @returns Injector map config keyed by lazy trigger.
- */
-function buildInjectorMap(lazyGroups: ResolvedLazyScriptGroup[]): InjectorMapConfig {
-	const map: InjectorMapConfig = {};
-
-	for (const group of lazyGroups) {
-		const scripts = normalizeScripts(group.scripts);
-		const lazy = group.lazy;
-
-		if ('on:idle' in lazy) {
-			map['on:idle'] = {
-				scripts: [...(map['on:idle']?.scripts ?? []), ...scripts],
-			};
-			continue;
-		}
-
-		if ('on:interaction' in lazy) {
-			const currentValue = map['on:interaction']?.value;
-			const nextValue = lazy['on:interaction'];
-
-			map['on:interaction'] = {
-				value: typeof currentValue === 'string' ? dedupeCsvValues([currentValue, nextValue]) : nextValue,
-				scripts: [...(map['on:interaction']?.scripts ?? []), ...scripts],
-			};
-			continue;
-		}
-
-		if ('on:visible' in lazy) {
-			const currentValue = map['on:visible']?.value;
-			const currentThreshold = typeof currentValue === 'string' ? currentValue : undefined;
-			const nextValue = lazy['on:visible'];
-
-			map['on:visible'] = {
-				...(nextValue === true
-					? currentThreshold
-						? { value: currentThreshold }
-						: {}
-					: { value: String(nextValue) }),
-				scripts: [...(map['on:visible']?.scripts ?? []), ...scripts],
-			};
-			continue;
-		}
-
-		throw new Error(
-			`Invalid lazy options: must specify on:idle, on:interaction, or on:visible. Received: ${JSON.stringify(lazy)}`,
-		);
-	}
-
-	for (const key of Object.keys(map)) {
-		const scripts = map[key]?.scripts;
-		if (scripts) {
-			map[key] = {
-				...map[key],
-				scripts: Array.from(new Set(scripts)),
-			};
-		}
-	}
-
-	return map;
-}
-
-/**
- * Creates a safe JSON payload string for `<script type="ecopages/injector-map">`.
- *
- * @param lazyGroups Lazy script groups resolved during dependency processing.
- * @returns Escaped JSON string safe for inline script embedding.
- */
-export function buildInjectorMapScript(lazyGroups: ResolvedLazyScriptGroup[]): string {
-	const map = buildInjectorMap(lazyGroups);
-	return JSON.stringify(map).replace(/<\/script/gi, '<\\/script');
-}