@nan0web/ui 1.9.0 → 1.11.0

package/types/core/Intent.d.ts

@@ -12,6 +12,65 @@ export function isModelSchema(schema: any): boolean;
  * @returns {intent is Intent}
  */
 export function validateIntent(intent: any): intent is Intent;
+/**
+ * Create an ask intent.
+ *
+ * Two modes:
+ *   ask('amount', { help: 'Enter amount', type: 'number' })  → single field
+ *   ask('transfer', TransferMoneyModel)                       → full Model form
+ *
+ * @param {string} field - Field name or form name.
+ * @param {object | Function} schema - Field descriptor or Model-as-Schema class.
+ * @returns {AskIntent}
+ */
+export function ask(field: string, schema: object | Function): AskIntent;
+/**
+ * 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: string, value?: number, totalOrId?: number | string, id?: string): ProgressIntent;
+export function log(level: any, message: any, data?: {}): {
+    type: string;
+    level: any;
+    message: any;
+};
+/**
+ * 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: string, props?: object): RenderIntent;
+/**
+ * Create a result intent.
+ * @param {*} data - The raw result data.
+ * @returns {ResultIntent}
+ */
+export function result(data: any): ResultIntent;
+/**
+ * @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: string | any, level?: ShowLevel | ShowData, data?: ShowData): ShowIntent;
+/**
+ * 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: string, context?: AgentContext): AgentIntent;
 /**
  * @typedef {Object} FieldSchema
  * @property {string} help - Human-readable label / i18n key.
@@ -36,16 +95,28 @@ export function validateIntent(intent: any): intent is Intent;
  * @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.
  */
 /**
  * Final return value from the generator.
@@ -53,9 +124,39 @@ export function validateIntent(intent: any): intent is Intent;
  * @property {'result'} type
  * @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 to an AskIntent. Adapter provides the collected value.
@@ -64,6 +165,20 @@ export function validateIntent(intent: any): intent is Intent;
  * @property {*} value - The value matching schema.type (collected from user / LLM / test fixture).
  * @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.
+ */
 /**
  * Special response that Adapters can send to abort the generator.
  *
@@ -80,22 +195,15 @@ export function validateIntent(intent: any): intent is Intent;
  */
 /**
  * Union of all possible responses an Adapter can send back via iterator.next().
- * @typedef {AskResponse | AbortResponse | undefined} IntentResponse
+ * @typedef {AskResponse | AgentResponse | AbortResponse | undefined} IntentResponse
  */
-export const INTENT_TYPES: readonly ["ask", "progress", "log"];
-export function ask(field: string, schema: object | Function): AskIntent;
-export function progress(message: any): {
-    type: string;
-    message: any;
-};
-export function log(level: any, message: any, data?: {}): {
-    type: string;
-    level: any;
-    message: any;
-};
-export function result(data: any): {
-    type: string;
-    data: any;
+/**
+ * @typedef {'ask' | 'show' | 'progress' | 'render' | 'agent'} IntentType
+ */
+export const INTENT_TYPES: readonly ["ask", "progress", "show", "log", "render", "agent"];
+export type ShowData = {
+    component?: any;
+    model?: import("@nan0web/types").Model | undefined;
 };
 export type FieldSchema = {
     /**
@@ -156,7 +264,11 @@ export type ProgressIntent = {
      */
     value?: number | undefined;
     /**
-     * - Progress ID for tracking multiple parallel operations.
+     * - Absolute total (if value is absolute).
+     */
+    total?: number | undefined;
+    /**
+     * - Progress ID for tracking by Adapter to calculate speed/eta.
      */
     id?: string | undefined;
     /**
@@ -164,15 +276,28 @@ export type ProgressIntent = {
      */
     message: string;
 };
+export type ShowLevel = "info" | "warn" | "error" | "success";
+export type LogLevel = ShowLevel;
 /**
- * Model emits a log message. No response expected.
+ * Model emits a show message. No response expected.
  * Message MUST come from the Model (i18n static field value).
  */
+export type ShowIntent = {
+    type: "show";
+    level: ShowLevel;
+    /**
+     * - Show message from Model (i18n static field value).
+     */
+    message: string;
+};
+/**
+ * Model emits a log message intended for debugging/developer (Not UI).
+ */
 export type LogIntent = {
     type: "log";
-    level: "info" | "warn" | "error" | "success";
+    level: LogLevel;
     /**
-     * - Log message from Model (i18n static field value).
+     * - Internal log message.
      */
     message: string;
 };
@@ -186,10 +311,67 @@ export type ResultIntent = {
      */
     data: any;
 };
+/**
+ * Model requests rendering of a pure UI component (Header, Footer, Static Map).
+ * No response expected from the logic loop.
+ */
+export type RenderIntent = {
+    type: "render";
+    /**
+     * - Component name (e.g. 'App.Layout.Header').
+     */
+    component: string;
+    /**
+     * - Static props for the component.
+     */
+    props: object;
+};
+/**
+ * Contextual data and attachments for the AI subagent.
+ */
+export type AgentContext = {
+    /**
+     * - List of instructions or guidelines (e.g. ['Use 1-char emojis only']).
+     */
+    instructions?: string[] | undefined;
+    /**
+     * - Hash map of file paths to their string contents.
+     */
+    files?: Record<string, string> | undefined;
+    /**
+     * - Any arbitrary JSON data (e.g. parsed errors, ASTs, metadata) useful for the task.
+     */
+    data?: Record<string, any> | undefined;
+};
+/**
+ * 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.
+ */
+export type AgentIntent = {
+    type: "agent";
+    /**
+     * - The instructional task for the AI agent.
+     */
+    task: string;
+    /**
+     * - Contextual data, files, and instructions for the task.
+     */
+    context: AgentContext;
+    /**
+     * - Helper to format task and context as an LLM prompt.
+     */
+    toPrompt: () => string;
+};
 /**
  * Union of all possible yielded intents.
  */
-export type Intent = AskIntent | ProgressIntent | LogIntent;
+export type Intent = (AskIntent | ProgressIntent | LogIntent | ShowIntent | RenderIntent | AgentIntent | ResultIntent) & {
+    $value?: any;
+    $success?: boolean;
+    $files?: Record<string, string>;
+    $message?: string;
+};
 /**
  * Response to an AskIntent. Adapter provides the collected value.
  * The value MUST conform to the type described in the requested FieldSchema.
@@ -204,6 +386,29 @@ export type AskResponse = {
      */
     cancelled?: boolean | undefined;
 };
+/**
+ * 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.
+ */
+export type AgentResponse = {
+    /**
+     * - True if the agent successfully processed the task.
+     */
+    success: boolean;
+    /**
+     * - Hash map of fully resolved, updated file contents.
+     */
+    files?: Record<string, string> | undefined;
+    /**
+     * - Optional summary or explanation returned by the AI.
+     */
+    message?: string | undefined;
+};
 /**
  * Special response that Adapters can send to abort the generator.
  *
@@ -227,4 +432,5 @@ export type AbortResponse = {
 /**
  * Union of all possible responses an Adapter can send back via iterator.next().
  */
-export type IntentResponse = AskResponse | AbortResponse | undefined;
+export type IntentResponse = AskResponse | AgentResponse | AbortResponse | undefined;
+export type IntentType = "ask" | "show" | "progress" | "render" | "agent";

package/types/core/IntentErrorModel.d.ts

@@ -19,6 +19,10 @@ export class IntentErrorModel {
         help: string;
         error: string;
     };
+    static render_missing_component: {
+        help: string;
+        error: string;
+    };
     static adapter_missing_ask: {
         help: string;
         error: string;

package/types/core/Message/Message.d.ts

@@ -61,9 +61,9 @@ export default class UiMessage extends Message {
      */
     constructor(input?: any);
     /** @type {string} */
-    type: string;
-    /** @type {string} */
     id: string;
+    /** @type {string} */
+    type: string;
     /**
      * Validates the message body against its schema.
      *

package/types/core/Message/OutputMessage.d.ts

@@ -18,8 +18,6 @@ export default class OutputMessage extends UiMessage {
      * @returns {OutputMessage}
      */
     static from(input: any): OutputMessage;
-    /** @type {string[]} */
-    body: string[];
     /** @type {Object} */
     meta: any;
     /** @type {Error|null} */

package/types/core/index.d.ts

@@ -7,10 +7,11 @@ export { default as UiAdapter } from "./UiAdapter.js";
 export { IntentErrorModel } from "./IntentErrorModel.js";
 export { runGenerator } from "./GeneratorRunner.js";
 export { MaskHandler } from "./MaskHandler.js";
+export { LayoutModel } from "../domain/LayoutModel.js";
 import UIStream from './Stream.js';
 import StreamEntry from './StreamEntry.js';
 import UIForm from './Form/Form.js';
 export { UIStream, UIStream as UiStream, StreamEntry, StreamEntry as UiStreamEntry, UIForm, UIForm as UiForm };
 export { default as Error, CancelError } from "./Error/index.js";
 export { runFlow, flow, View, Prompt, Stream, Alert, Toast, Badge, Text, Table, Input, Select, Confirm, Multiselect, Mask, Password, Spinner, Progress, default as Flow } from "./Flow.js";
-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";