@nan0web/ui 1.9.0 → 1.11.0

package/src/core/GeneratorRunner.js

@@ -12,7 +12,7 @@
  * instead of writing its own while(true) loop.
  */
 
-import { validateIntent } from './Intent.js'
+import { validateIntent, result } from './Intent.js'
 import { IntentErrorModel } from './IntentErrorModel.js'
 
 /**
@@ -21,8 +21,14 @@ import { IntentErrorModel } from './IntentErrorModel.js'
  *   Handler for 'ask' intents. Must return { value: ... }.
  * @property {(intent: import('./Intent.js').ProgressIntent) => void | Promise<void>} [progress]
  *   Handler for 'progress' intents. Optional (defaults to no-op).
+ * @property {(intent: import('./Intent.js').ShowIntent) => void | Promise<void>} [show]
+ *   Handler for 'show' intents. Optional (defaults to no-op).
  * @property {(intent: import('./Intent.js').LogIntent) => void | Promise<void>} [log]
- *   Handler for 'log' intents. Optional (defaults to no-op).
+ *   Handler for 'log' intents. Optional.
+ * @property {(intent: import('./Intent.js').AgentIntent) => Promise<import('./Intent.js').AgentResponse>} [agent]
+ *   Handler for 'agent' intents (AI Subagents). Optional (fallback to show if not implemented).
+ * @property {(intent: import('./Intent.js').RenderIntent) => void | Promise<void>} [render]
+ *   Handler for 'render' intents (visual component injection). Optional.
  * @property {(intent: import('./Intent.js').ResultIntent) => void | Promise<void>} [result]
  *   Handler for the final 'result'. Optional (defaults to no-op).
  */
@@ -35,6 +41,9 @@ import { IntentErrorModel } from './IntentErrorModel.js'
  *   Set to a positive value for CLI/Chat adapters where hanging is unacceptable.
  * @property {AbortSignal} [signal]
  *   External AbortSignal for cancellation from outside.
+ * @property {import('./Intent.js').Intent[]} [trace]
+ *   Array where all executed intents will be sequentially recorded.
+ *   Useful for generating 'crash reports' or Nan0Spec files on failure.
  */
 
 /**
@@ -51,18 +60,18 @@ function withTimeout(promise, ms, label) {
 	if (!ms || ms <= 0) return promise
 
 	return new Promise((resolve, reject) => {
-		const timer = setTimeout(() => {
+		const timer = globalThis.setTimeout(() => {
 			const error = IntentErrorModel.error('timeout', { label, ms })
 			reject(error)
 		}, ms)
 
 		promise.then(
 			(val) => {
-				clearTimeout(timer)
+				globalThis.clearTimeout(timer)
 				resolve(val)
 			},
 			(err) => {
-				clearTimeout(timer)
+				globalThis.clearTimeout(timer)
 				reject(err)
 			},
 		)
@@ -103,7 +112,7 @@ export async function runGenerator(generator, handlers, options = {}) {
 	while (true) {
 		// ─── Check external abort signal ───
 		if (signal?.aborted) {
-			await generator.return({ type: 'result', data: null })
+			await generator.return(/** @type {any} */ (result(null)))
 			const error = IntentErrorModel.error('aborted')
 			error.name = 'AbortError'
 			throw error
@@ -138,6 +147,11 @@ export async function runGenerator(generator, handlers, options = {}) {
 		// ─── Validate intent structure (the Judge) ───
 		validateIntent(intent)
 
+		// Record intent into the global trace if provided (for Crash Reports in Nan0Spec format).
+		if (options.trace && Array.isArray(options.trace)) {
+			options.trace.push(intent)
+		}
+
 		// ─── Dispatch to adapter handler ───
 		switch (intent.type) {
 			case 'ask': {
@@ -165,7 +179,7 @@ export async function runGenerator(generator, handlers, options = {}) {
 					break
 				}
 
-				// Run field validation if schema has a validator (the Judge again)
+				// Run field validation if schema has a validator
 				if (!intent.model) {
 					/** @type {import('./Intent.js').FieldSchema} */
 					const fieldSchema = /** @type {import('./Intent.js').FieldSchema} */ (intent.schema)
@@ -180,6 +194,17 @@ export async function runGenerator(generator, handlers, options = {}) {
 					}
 				}
 
+				if (options.trace && Array.isArray(options.trace)) {
+					const lastTrace = options.trace[options.trace.length - 1]
+					if (lastTrace && lastTrace.type === 'ask') {
+						// Store raw data for Crash Reports & Nan0Spec serialization
+						lastTrace.$value =
+							typeof response.value === 'object' && response.value !== null
+								? JSON.parse(JSON.stringify(response.value))
+								: response.value
+					}
+				}
+
 				// Instantiate Model-as-Schema class with collected data
 				if (intent.model && typeof intent.schema === 'function') {
 					const ModelClass = /** @type {new (data: any) => any} */ (intent.schema)
@@ -198,6 +223,14 @@ export async function runGenerator(generator, handlers, options = {}) {
 				break
 			}
 
+			case 'show': {
+				if (handlers.show) {
+					await handlers.show(intent)
+				}
+				nextVal = undefined
+				break
+			}
+
 			case 'log': {
 				if (handlers.log) {
 					await handlers.log(intent)
@@ -206,6 +239,43 @@ export async function runGenerator(generator, handlers, options = {}) {
 				break
 			}
 
+			case 'render': {
+				if (handlers.render) {
+					await handlers.render(intent)
+				}
+				nextVal = undefined
+				break
+			}
+
+			case 'agent': {
+				if (handlers.agent) {
+					const response = await handlers.agent(intent)
+
+					if (options.trace && Array.isArray(options.trace)) {
+						const lastTrace = options.trace[options.trace.length - 1]
+						if (lastTrace && lastTrace.type === 'agent') {
+							// Record agent response for full trace replayability
+							/** @type {any} */ ;(lastTrace).$success = response.success
+							if (response.files) /** @type {any} */ (lastTrace).$files = response.files
+							if (response.message) /** @type {any} */ (lastTrace).$message = response.message
+						}
+					}
+
+					nextVal = response
+				} else {
+					// Fallback to show if agent goes unsupported by adapter
+					if (handlers.show) {
+						await handlers.show({
+							type: 'show',
+							level: 'warn',
+							message: `[Agent Task] ${intent.task}`,
+						})
+					}
+					nextVal = { success: false, message: 'Agent not supported by current UI adapter' }
+				}
+				break
+			}
+
 			default:
 				throw IntentErrorModel.error('unhandled_intent', { type: /** @type {any} */ (intent).type })
 		}

package/src/core/InputAdapter.js

@@ -8,7 +8,7 @@ import UiMessage from './Message/Message.js'
  * @class InputAdapter
  * @extends Event
  */
-export default class InputAdapter extends Event {
+export class InputAdapter extends Event {
 	static CancelError = CancelError
 	/** @returns {typeof CancelError} */
 	get CancelError() {
@@ -59,3 +59,5 @@ export default class InputAdapter extends Event {
 		throw new Error('select() method must be implemented in subclass')
 	}
 }
+
+export default InputAdapter

package/src/core/Intent.js

@@ -38,17 +38,32 @@ import { IntentErrorModel } from './IntentErrorModel.js'
  * @typedef {Object} ProgressIntent
  * @property {'progress'} type
  * @property {number} [value] - Progress value (0-1).
- * @property {string} [id] - Progress ID for tracking multiple parallel operations.
+ * @property {number} [total] - Absolute total (if value is absolute).
+ * @property {string} [id] - Progress ID for tracking by Adapter to calculate speed/eta.
  * @property {string} message - Status message from Model (i18n static field value).
  */
 
 /**
- * Model emits a log message. No response expected.
+ * @typedef {'info' | 'warn' | 'error' | 'success'} ShowLevel
+ */
+
+/** @typedef {ShowLevel} LogLevel */
+
+/**
+ * Model emits a show message. No response expected.
  * Message MUST come from the Model (i18n static field value).
+ * @typedef {Object} ShowIntent
+ * @property {'show'} type
+ * @property {ShowLevel} level
+ * @property {string} message - Show message from Model (i18n static field value).
+ */
+
+/**
+ * Model emits a log message intended for debugging/developer (Not UI).
  * @typedef {Object} LogIntent
  * @property {'log'} type
- * @property {'info' | 'warn' | 'error' | 'success'} level
- * @property {string} message - Log message from Model (i18n static field value).
+ * @property {LogLevel} level
+ * @property {string} message - Internal log message.
  */
 
 /**
@@ -58,9 +73,42 @@ import { IntentErrorModel } from './IntentErrorModel.js'
  * @property {*} data - The raw result data (JSON-serializable).
  */
 
+/**
+ * Model requests rendering of a pure UI component (Header, Footer, Static Map).
+ * No response expected from the logic loop.
+ * @typedef {Object} RenderIntent
+ * @property {'render'} type
+ * @property {string} component - Component name (e.g. 'App.Layout.Header').
+ * @property {object} props - Static props for the component.
+ */
+
+/**
+ * Contextual data and attachments for the AI subagent.
+ * @typedef {Object} AgentContext
+ * @property {string[]} [instructions] - List of instructions or guidelines (e.g. ['Use 1-char emojis only']).
+ * @property {Record<string, string>} [files] - Hash map of file paths to their string contents.
+ * @property {Record<string, any>} [data] - Any arbitrary JSON data (e.g. parsed errors, ASTs, metadata) useful for the task.
+ */
+
+/**
+ * Model delegates a task to an AI subagent. The Adapter should launch the agent
+ * with the provided task and context, and return the result. If the agent is skipped,
+ * it returns { success: false } but allows user to generate a prompt.
+ * @typedef {Object} AgentIntent
+ * @property {'agent'} type
+ * @property {string} task - The instructional task for the AI agent.
+ * @property {AgentContext} context - Contextual data, files, and instructions for the task.
+ * @property {() => string} toPrompt - Helper to format task and context as an LLM prompt.
+ */
+
 /**
  * Union of all possible yielded intents.
- * @typedef {AskIntent | ProgressIntent | LogIntent} Intent
+ * @typedef {(AskIntent | ProgressIntent | LogIntent | ShowIntent | RenderIntent | AgentIntent | ResultIntent) & {
+ *   $value?: any;
+ *   $success?: boolean;
+ *   $files?: Record<string, string>;
+ *   $message?: string;
+ * }} Intent
  */
 
 // ─── Response Types (Adapter → Model) ───
@@ -73,6 +121,21 @@ import { IntentErrorModel } from './IntentErrorModel.js'
  * @property {boolean} [cancelled] - Whether the user cancelled this interaction (e.g. pressed ESC).
  */
 
+/**
+ * Response to an AgentIntent.
+ * The underlying Adapter (Orchestrator) is responsible for communicating with the LLM,
+ * enforcing output formats (e.g. Unified Diff or Tool Calls like `updateFile`),
+ * and resolving common LLM hallucinations (like Grok truncating code with `// ...`).
+ *
+ * The Model (e.g. IconsAuditor) receives this clean, resolved response and does not
+ * need to parse Markdown or interpret diffs itself.
+ *
+ * @typedef {Object} AgentResponse
+ * @property {boolean} success - True if the agent successfully processed the task.
+ * @property {Record<string, string>} [files] - Hash map of fully resolved, updated file contents.
+ * @property {string} [message] - Optional summary or explanation returned by the AI.
+ */
+
 // ─── Abort Support ───
 
 /**
@@ -92,10 +155,14 @@ import { IntentErrorModel } from './IntentErrorModel.js'
 
 /**
  * Union of all possible responses an Adapter can send back via iterator.next().
- * @typedef {AskResponse | AbortResponse | undefined} IntentResponse
+ * @typedef {AskResponse | AgentResponse | AbortResponse | undefined} IntentResponse
+ */
+
+/**
+ * @typedef {'ask' | 'show' | 'progress' | 'render' | 'agent'} IntentType
  */
 
-export const INTENT_TYPES = /** @type {const} */ (['ask', 'progress', 'log'])
+export const INTENT_TYPES = /** @type {const} */ (['ask', 'progress', 'show', 'log', 'render', 'agent'])
 
 /**
  * Detects if a value is a Model-as-Schema class (has static fields with `help`).
@@ -104,7 +171,7 @@ export const INTENT_TYPES = /** @type {const} */ (['ask', 'progress', 'log'])
  */
 export function isModelSchema(schema) {
 	if (typeof schema !== 'function') return false
-	return Object.keys(schema).some((key) => {
+	return Object.getOwnPropertyNames(schema).some((key) => {
 		const meta = schema[key]
 		return meta && typeof meta === 'object' && 'help' in meta
 	})
@@ -133,16 +200,29 @@ export function validateIntent(intent) {
 		}
 		// Accept both: plain schema {help: '...'} and Model-as-Schema class/instance
 		const isModel = !!intent.model
-		if (!isModel && (!intent.schema || typeof intent.schema !== 'object' || !('help' in intent.schema))) {
+		if (
+			!isModel &&
+			(!intent.schema || typeof intent.schema !== 'object' || !('help' in intent.schema))
+		) {
 			throw IntentErrorModel.error('ask_missing_schema_help')
 		}
 	}
-	if (intent.type === 'progress' || intent.type === 'log') {
-		const isComponentLog = intent.type === 'log' && intent.component
-		if (!isComponentLog && typeof intent.message !== 'string') {
+	if (intent.type === 'progress' || intent.type === 'show' || intent.type === 'log') {
+		const isComponentShow = (intent.type === 'show' || intent.type === 'log') && intent.component
+		if (!isComponentShow && typeof intent.message !== 'string') {
 			throw IntentErrorModel.error('intent_missing_message', { type: intent.type })
 		}
 	}
+	if (intent.type === 'render') {
+		if (typeof intent.component !== 'string' || !intent.component) {
+			throw IntentErrorModel.error('render_missing_component')
+		}
+	}
+	if (intent.type === 'agent') {
+		if (typeof intent.task !== 'string' || !intent.task) {
+			throw IntentErrorModel.error('agent_missing_task')
+		}
+	}
 	return true
 }
 
@@ -157,13 +237,131 @@ export function validateIntent(intent) {
  * @param {object | Function} schema - Field descriptor or Model-as-Schema class.
  * @returns {AskIntent}
  */
-export const ask = (field, schema) => {
+export function ask(field, schema) {
 	if (isModelSchema(schema)) {
 		return { type: 'ask', field, schema, model: true }
 	}
 	return { type: 'ask', field, schema }
 }
 
-export const progress = (message) => ({ type: 'progress', message })
-export const log = (level, message, data = {}) => ({ type: 'log', level, message, ...data })
-export const result = (data) => ({ type: 'result', data })
+/**
+ * Create a progress intent.
+ * @param {string} message - Status message from Model (i18n static field value).
+ * @param {number} [value=0] - Progress value (current step or percentage).
+ * @param {number|string} [totalOrId] - Absolute total steps (number) OR progress tracking ID (string).
+ * @param {string} [id='default'] - Progress ID (if total is provided).
+ * @returns {ProgressIntent}
+ */
+export function progress(message, value = 0, totalOrId, id) {
+	let total = undefined
+	let progressId = 'default'
+
+	if (typeof totalOrId === 'number') {
+		total = totalOrId
+		if (typeof id === 'string') progressId = id
+	} else if (typeof totalOrId === 'string') {
+		progressId = totalOrId
+	}
+
+	return { type: 'progress', message, value, total, id: progressId }
+}
+
+export function log(level, message, data = {}) {
+	return { type: 'log', level, message, ...data }
+}
+
+/**
+ * Create a render intent.
+ * @param {string} component - Component name (e.g. 'App.Layout.Header').
+ * @param {object} [props] - Static props for the component.
+ * @returns {RenderIntent}
+ */
+export function render(component, props = {}) {
+	return { type: 'render', component, props }
+}
+
+/**
+ * Create a result intent.
+ * @param {*} data - The raw result data.
+ * @returns {ResultIntent}
+ */
+export function result(data) {
+	return { type: 'result', data }
+}
+
+/**
+ * @typedef {Object} ShowData
+ * @property {any} [component]
+ * @property {import('@nan0web/types').Model} [model]
+ */
+/**
+ * Create a show intent.
+ * @param {string | any} message Message to display.
+ * @param {ShowLevel|ShowData} [level='info'] Level of message or additional data then `level = 'info'`.
+ * @param {ShowData} [data={}] Additional data to display.
+ * @returns {ShowIntent}
+ */
+export function show(message, level = 'info', data = {}) {
+	if ('string' === typeof level) {
+		return { type: 'show', level, message, ...data }
+	}
+	return { type: 'show', level: 'info', message, ...level, ...data }
+}
+
+/**
+ * Create an agent intent to delegate a task to an AI subagent.
+ * @param {string} task - The instructional task for the AI agent.
+ * @param {AgentContext} [context={}] - Contextual data (files, errors, docs).
+ * @returns {AgentIntent}
+ */
+export function agent(task, context = {}) {
+	return {
+		type: 'agent',
+		task,
+		context,
+		toPrompt() {
+			let ctxStr = ''
+			if (this.context.data) {
+				try {
+					ctxStr = JSON.stringify(this.context.data, null, 2)
+				} catch (e) {
+					ctxStr = String(this.context.data)
+				}
+			}
+
+			// Format input files for the LLM using the boundary concept
+			const filesStr = Object.entries(this.context.files || {})
+				.map(([path, content]) => `---boundary:${path}---\n${content}\n---boundary---`)
+				.join('\n\n')
+
+			const outputRules = `
+[Output Format Rules]
+You must return your code modifications using the following strictly parsable boundary format. Do NOT use markdown code blocks (\`\`\`) or JSON for your code outputs.
+
+To replace an ENTIRE file:
+---boundary:path/to/file.js---
+<full new file content here>
+---boundary---
+
+To replace a SPECIFIC SNIPPET (e.g. replacing 3 lines starting at line 33):
+---boundary:path/to/file.js:33:3---
+<new snippet content here>
+---boundary---
+`
+			const inst = Array.isArray(this.context.instructions)
+				? this.context.instructions.join('\n')
+				: this.context.instructions
+
+			return [
+				`[Subagent Task]`,
+				this.task,
+				inst ? `\n[Instructions]\n${inst}` : '',
+				ctxStr ? `\n[Context]\n${ctxStr}` : '',
+				filesStr ? `\n[Files]\n${filesStr}` : '',
+				outputRules,
+			]
+				.filter(Boolean)
+				.join('\n')
+		},
+	}
+}

package/src/core/IntentErrorModel.js

@@ -39,7 +39,12 @@ export class IntentErrorModel {
 
 	static intent_missing_message = {
 		help: 'Progress and Log intents require a message',
-		error: '\'{type}\' intent requires a "message" string',
+		error: "'{type}' intent requires a \"message\" string",
+	}
+
+	static render_missing_component = {
+		help: 'Render intent requires a component name',
+		error: 'Render intent requires a non-empty "component" string',
 	}
 
 	// ─── Runner Contract Errors ───

package/src/core/Message/Message.js

@@ -43,11 +43,6 @@ export default class UiMessage extends Message {
 		NAVIGATION: 'navigation',
 	}
 
-	/** @type {string} */
-	type = ''
-	/** @type {string} */
-	id = ''
-
 	/**
 	 * Creates a UiMessage.
 	 *
@@ -56,9 +51,11 @@ export default class UiMessage extends Message {
 	constructor(input = {}) {
 		super(input)
 
-		const { type = this.type, id = this.id } = input
+		const { type, id } = input
+		/** @type {string} */
 		this.id = id || `ui-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
-		this.type = String(type)
+		/** @type {string} */
+		this.type = type ? String(type) : ''
 
 		if (!('body' in input) && 'content' in input) {
 			this.body = Array.isArray(input.content) ? input.content : [input.content]

package/src/core/Message/OutputMessage.js

@@ -14,15 +14,6 @@ export default class OutputMessage extends UiMessage {
 		CRITICAL: 3,
 	}
 
-	/** @type {string[]} */
-	body
-	/** @type {Object} */
-	meta = {}
-	/** @type {Error|null} */
-	error = null
-	/** @type {number} */
-	priority = OutputMessage.PRIORITY.NORMAL
-
 	/**
 	 * Creates an OutputMessage.
 	 *
@@ -41,14 +32,18 @@ export default class OutputMessage extends UiMessage {
 
 		const contentSource = 'body' in input ? body : 'content' in input ? content : []
 
+		/** @type {string[]} */
 		this.body = Array.isArray(contentSource)
 			? contentSource
 			: contentSource
 				? [String(contentSource)]
 				: []
 
+		/** @type {Object} */
 		this.meta = meta
+		/** @type {Error|null} */
 		this.error = error instanceof Error ? error : error ? new Error(String(error)) : null
+		/** @type {number} */
 		this.priority = Number(priority)
 
 		if (!this.type && this.error) {

package/src/core/Stream.js

@@ -44,19 +44,30 @@ export default class UIStream {
 	static async process(signal, generatorFn, onProgress, onError, onComplete) {
 		const iter = generatorFn()
 
+		/** @type {Promise<never>} */
+		const abortPromise = new Promise((_, reject) => {
+			const onAbort = () => reject(new DOMException('The operation was aborted', 'AbortError'))
+			if (signal.aborted) return onAbort()
+			signal.addEventListener('abort', onAbort, { once: true })
+		})
+
 		try {
-			for await (const item of iter) {
-				if (signal.aborted) {
-					throw new DOMException('Aborted', 'AbortError')
+			while (true) {
+				const { value: item, done } = await Promise.race([iter.next(), abortPromise])
+
+				if (done) {
+					if (item) onComplete?.(item)
+					break
 				}
 
 				if (item.done) {
 					onComplete?.(item)
 					break
-				} else if (item.error) {
+				}
+
+				if (item.error) {
 					onError?.(item.error, item)
 				} else {
-					// Intermediate results
 					onProgress?.(null, item)
 				}
 			}

package/src/core/StreamEntry.js

@@ -2,30 +2,6 @@
  * Represents an entry in a stream with value, completion status, cancellation status, and error message.
  */
 export default class StreamEntry {
-	/**
-	 * The value of the stream entry.
-	 * @type {any}
-	 */
-	value = undefined
-
-	/**
-	 * Indicates if the stream entry is done (completed).
-	 * @type {boolean}
-	 */
-	done = false
-
-	/**
-	 * Indicates if the stream entry has been cancelled.
-	 * @type {boolean}
-	 */
-	cancelled = false
-
-	/**
-	 * Error message associated with the stream entry.
-	 * @type {string}
-	 */
-	error = ''
-
 	/**
 	 * Creates a new StreamEntry instance.
 	 * @param {Object} [input={}] - Input object to initialize the stream entry.
@@ -36,14 +12,30 @@ export default class StreamEntry {
 	 */
 	constructor(input = {}) {
 		const {
-			value = this.value,
-			done = this.done,
-			cancelled = this.cancelled,
-			error = this.error,
+			value = undefined,
+			done = false,
+			cancelled = false,
+			error = '',
 		} = input
+		/**
+		 * The value of the stream entry.
+		 * @type {any}
+		 */
 		this.value = value
+		/**
+		 * Indicates if the stream entry is done (completed).
+		 * @type {boolean}
+		 */
 		this.done = Boolean(done)
+		/**
+		 * Indicates if the stream entry has been cancelled.
+		 * @type {boolean}
+		 */
 		this.cancelled = Boolean(cancelled)
+		/**
+		 * Error message associated with the stream entry.
+		 * @type {string}
+		 */
 		this.error = String(error)
 	}
 

package/src/core/index.js

@@ -41,8 +41,9 @@ export {
 export { default as Flow } from './Flow.js'
 
 // OLMUI Generator Engine — Intent-based Model→Adapter contract
-export { validateIntent, ask, progress, log, result, INTENT_TYPES, isModelSchema } from './Intent.js'
+export { validateIntent, ask, progress, log, render, result, INTENT_TYPES, isModelSchema } from './Intent.js'
 export { IntentErrorModel } from './IntentErrorModel.js'
 export { runGenerator } from './GeneratorRunner.js'
 
 export { MaskHandler } from './MaskHandler.js'
+export { LayoutModel } from '../domain/LayoutModel.js'