@nan0web/ui 1.10.0 → 1.11.0

package/README.md

@@ -158,8 +158,13 @@ These models follow the **Model-as-Schema** pattern.
 - `FooterModel` — copyright, version, social links
 - `HeroModel` — prominent call-to-action
 
+#### HTML5 Base Elements
+Fully typed zero-cost support for standard tags: `div`, `span`, `p`, `h1`-`h6`, `a`, `ul`, `table`, etc., plus SVG basics (`svg`, `path`, `rect`). Data must be standard `camelCase`.
+
 #### Component Models
-- `PricingModel` — plans with features and prices
+- `PricingModel` / `PricingSection` — plans with features and prices
+- `FeatureGrid` — grid of feature highlights
+- `ProfileDropdown` — user avatar and settings menu
 - `CommentModel` & `TestimonialModel` — social proof
 - `StatsModel` — data visualizations
 - `TimelineModel` — event history
@@ -180,14 +185,75 @@ const hero = new HeroModel({
 console.info(header.title) // ← NaN•Web
 console.info(hero.actions[0].title) // ← Get Started
 ```
-### Testing UI
+### Intent Generators (v1.11.0)
+
+From v1.11.0, Intent creators are standard named functions generating
+strict interactions (ask, progress, show, render, result).
+
+- `ask(field, schema)` — requests input from the environment.
+- `progress(message)` — updates a visual loader.
+- `show(message, level, data)` — displays a notification (replaces deprecated `log`).
+- `render(component, props)` — renders a specific component view.
+- `result(data)` — ends the model execution cleanly.
+
+How to use Intent generators? (v1.11.0)
+```js
+import { ask, show, result } from '@nan0web/ui'
+const nameIntent = ask('name', { help: 'Your name' })
+const msgIntent = show('Processing...', 'info')
+const endIntent = result({ ok: true })
+```
+### Testing UI (v1.11.0 Deterministic Testing)
 
 Core unit-tested to ensure stability in different environments.
+With **v1.11.0**, the architecture formally introduces `ScenarioTest` for zero-I/O deterministic testing.
 
+By lifting the asynchronous logic and providing an explicit scenario array, models are evaluated instantly without waiting on user prompt delays.
+
+How to test Model pipelines deterministically?
+```js
+import { ModelAsApp, ask, result, show } from '@nan0web/ui'
+import { ScenarioTest } from '@nan0web/ui/test/ScenarioTest.js'
+const { ModelAsApp, ask, result, show } = await import('./index.js')
+const { ScenarioTest } = await import('./test/ScenarioTest.js')
+class ShoppingCartApp extends ModelAsApp {
+	*run() {
+		const product = yield ask('product', { help: 'Select product' })
+		if (product?.value === 'laptop') {
+			yield show('Good choice!', 'ok')
+		}
+		const confirm = yield ask('confirm', { help: 'Confirm purchase?' })
+		return result({ product: product?.value, confirm: confirm?.value })
+	}
+}
+const res = await ScenarioTest.run(ShoppingCartApp, [
+	{ field: 'product', value: 'laptop' },
+	{ field: 'confirm', value: true }
+])
+```
+You can also verify exceptions and validation rules by observing the final error in ScenarioTest.
+
+How to test validation errors with ScenarioTest?
+```js
+import { ModelAsApp, ask, result } from '@nan0web/ui'
+import { ScenarioTest } from '@nan0web/ui/test/ScenarioTest.js'
+const { ModelAsApp, ask, result } = await import('./index.js')
+const { ScenarioTest } = await import('./test/ScenarioTest.js')
+class ValidatedApp extends ModelAsApp {
+	*run() {
+		const code = yield ask('code', { help: 'Enter code', required: true })
+		if (!code?.value) throw new Error('Code is mandatory')
+		return result({ code: code?.value })
+	}
+}
+const res = await ScenarioTest.run(ValidatedApp, [
+	{ field: 'code', value: '' } // Simulating empty response
+])
+```
 All components, adapters, and models are designed to be testable
 with minimal setup.
 
-How to test UI components with assertions?
+How to test visual UI components with assertions?
 ```js
 import { Welcome } from '@nan0web/ui'
 const output = Welcome({ user: { name: 'Test' } })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nan0web/ui",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "NaN•Web UI. One application logic (algorithm) and many UI.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -16,27 +16,51 @@
       "import": "./src/index.js",
       "types": "./types/index.d.ts"
     },
-    "./components": "./src/Component/index.js",
-    "./core": "./src/core/index.js",
-    "./domain": "./src/domain/index.js",
-    "./testing": "./src/testing/index.js",
+    "./components": {
+      "import": "./src/Component/index.js",
+      "types": "./types/Component/index.d.ts"
+    },
+    "./core": {
+      "import": "./src/core/index.js",
+      "types": "./types/core/index.d.ts"
+    },
+    "./domain": {
+      "import": "./src/domain/index.js",
+      "types": "./types/domain/index.d.ts"
+    },
+    "./inspect": {
+      "import": "./src/inspect.js",
+      "types": "./types/inspect.d.ts"
+    },
+    "./testing": {
+      "import": "./src/testing/index.js",
+      "types": "./types/testing/index.d.ts"
+    },
     "./cli-app": "./apps/cli/src/index.js",
     "./mobile-app": "./apps/mobile/src/index.js",
-    "./web-app": "./apps/web/src/App.jsx"
+    "./web-app": "./apps/web/src/App.jsx",
+    "./ui/cli": "./src/cli.js"
   },
   "keywords": [
     "ui",
     "nanoweb"
   ],
+  "nan0web": {
+    "workflowDir": "docs/{locale}/workflows",
+    "workflows": [
+      "olm-ui-architecture.md",
+      "olm-ui-architecture-core.md",
+      "olm-ui-architecture-adapters.md",
+      "forge-component.md",
+      "interface-welding.md"
+    ],
+    "inspectors": [
+      "./src/domain/app/SnapshotAuditor.js"
+    ]
+  },
   "author": "YaRaSLove (ЯRаСлав) <support@yaro.page>",
   "license": "ISC",
   "devDependencies": {
-    "@nan0web/event": "^1.0.1",
-    "@nan0web/i18n": "^1.1.0",
-    "@nan0web/release": "^1.0.2",
-    "@nan0web/test": "^1.1.3",
-    "@nan0web/ui-cli": "^2.9.0",
-    "@nan0web/ui-lit": "^1.1.0",
     "@playwright/test": "^1.58.2",
     "@rollup/plugin-yaml": "^4.1.2",
     "@vitest/coverage-v8": "^3.2.4",
@@ -45,43 +69,51 @@
     "knip": "^5.86.0",
     "lit": "^3.3.2",
     "vite": "^6.4.1",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@nan0web/db-fs": "1.2.1",
+    "@nan0web/event": "1.0.1",
+    "@nan0web/i18n": "1.5.0",
+    "@nan0web/inspect": "1.0.0",
+    "@nan0web/ui-cli": "2.12.3",
+    "@nan0web/test": "1.1.4",
+    "@nan0web/icons": "1.1.0",
+    "@nan0web/release": "1.0.3",
+    "@nan0web/nan0web.app": "0.1.0",
+    "@nan0web/ui-lit": "1.1.0"
   },
   "dependencies": {
-    "@nan0web/co": "^2.0.0",
-    "@nan0web/log": "^1.1.1",
-    "@nan0web/types": "^1.4.0",
     "string-width": "^7.2.0",
-    "@nan0web/core": "1.1.2"
+    "@nan0web/co": "2.0.1",
+    "@nan0web/log": "1.1.1",
+    "@nan0web/types": "1.7.2",
+    "@nan0web/core": "1.1.3"
   },
   "scripts": {
+    "prebuild": "rm -rf types/",
     "build": "tsc",
     "play": "node play/main.js",
-    "test:unit": "node --test --test-timeout=3333 \"src/**/*.test.js\"",
-    "test": "npm run test:unit && npm run test:ssg && npm run build",
+    "test:unit": "node --test --test-timeout=3333 \"src/*.test.js\" \"src/core/**/*.test.js\" \"src/domain/**/*.test.js\" \"src/test/*.test.js\" \"src/testing/**/*.test.js\"",
+    "test": "npm run test:unit && npm run test:audit && npm run build",
     "test:nan0test": "node --test --test-timeout=3333 \"src/**/*.test.js\" | nan0test parse --fail",
     "test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
     "test:coverage:collect": "nan0test coverage",
     "test:docs": "node --test src/README.md.js",
-    "release:spec": "node --test \"releases/**/*.spec.js\"",
-    "test:release": "node --test \"releases/**/*.test.js\"",
+    "release:spec": "node --test \"src/test/releases/**/*.test.js\"",
+    "test:release": "node --test \"src/test/releases/**/*.test.js\"",
     "test:status": "nan0test status --hide-name",
     "test:play": "node --test --test-timeout=3333 \"play/**/*.test.js\"",
     "test:snapshots": "node src/testing/GalleryGenerator.js",
     "test:gallery": "npm run test:snapshots && npx nan0gallery --dir=snapshots/core",
-    "test:audit": "node --test src/test/gallery_audit.test.js",
-    "test:ssg": "node --test --test-timeout=5000 \"src/test/ssg.test.js\"",
-    "test:e2e": "playwright test --ignore-snapshots test/e2e/components.spec.js test/e2e/debug-label.spec.js",
-    "test:e2e:slow": "E2E_SLOW=1 playwright test test/e2e/visual.spec.js",
-    "test:all": "npm run test && npm run test:docs && npm run test:play && npm run test:gallery && npm run test:audit && npm run test:e2e && npm run knip",
+    "test:audit": "nan0cli audit --dir snapshots/core --data .",
+    "test:stories": "node --test \"src/**/*.story.js\"",
+    "test:all": "npm run test && npm run test:docs && npm run test:play && npm run test:stories && npm run knip",
     "knip": "knip --production",
     "precommit": "npm test",
     "prepush": "npm test",
     "release": "nan0release publish",
     "clean": "rm -rf .cache/ && rm -rf dist/",
     "clean:modules": "rm -rf node_modules",
-    "docs:build-data": "node docs/site/scripts/generate-data.js",
-    "docs:dev": "node docs/site/scripts/generate-data.js && node docs/site/scripts/generate-pages.js && vite docs/site",
-    "docs:build": "node docs/site/scripts/generate-data.js && node docs/site/scripts/generate-pages.js && vite build docs/site"
+    "docs:dev": "nan0web run --data docs --index README --port 4270",
+    "docs:build": "nan0web build --data docs --index README --locale uk"
   }
 }

package/src/App/Command/DepsCommand.js

@@ -1,23 +1,22 @@
 import UiMessage from '../../core/Message/Message.js'
 
 class DepsCommandBody {
-	fix = false
 	static fix = {
 		help: 'Fix dependencies',
 		defaultValue: false,
 	}
 	constructor(input = {}) {
-		const { fix = this.fix } = input
+		const { fix = DepsCommandBody.fix.defaultValue } = input
+		this.fix = !!fix
 	}
 }
 
 export class DepsCommand extends UiMessage {
 	static Body = DepsCommandBody
-	/** @type {DepsCommandBody} */
-	body
 	constructor(input = {}) {
 		const { body = new DepsCommandBody() } = UiMessage.parseBody(input, DepsCommandBody)
 		super(input)
+		/** @type {DepsCommandBody} */
 		this.body = body
 	}
 }

package/src/Frame/Props.js

@@ -53,24 +53,6 @@ class FrameProps extends ObjectWithAlias {
 		s: 'strikethrough',
 	}
 
-	/** @type {string} Text color */
-	color = ''
-
-	/** @type {string} Background color */
-	bgColor = ''
-
-	/** @type {boolean} Bold text flag */
-	bold = false
-
-	/** @type {boolean} Italic text flag */
-	italic = false
-
-	/** @type {boolean} Underline text flag */
-	underline = false
-
-	/** @type {boolean} Strikethrough text flag */
-	strikethrough = false
-
 	/**
 	 * @param {object} props - Frame properties
 	 * @param {string} [props.color=""] - Text color
@@ -90,11 +72,23 @@ class FrameProps extends ObjectWithAlias {
 			underline = false,
 			strikethrough = false,
 		} = props
+		
+		/** @type {string} Text color */
 		this.color = color
+		
+		/** @type {string} Background color */
 		this.bgColor = bgColor
+		
+		/** @type {boolean} Bold text flag */
 		this.bold = bold
+		
+		/** @type {boolean} Italic text flag */
 		this.italic = italic
+		
+		/** @type {boolean} Underline text flag */
 		this.underline = underline
+		
+		/** @type {boolean} Strikethrough text flag */
 		this.strikethrough = strikethrough
 	}
 }

package/src/InterfaceTemplate/InterfaceTemplate.js

@@ -22,13 +22,15 @@ export default class InterfaceTemplate {
 	 */
 	static requiredMethods = ['render', 'ask']
 
-	/**
-	 * The name of this interface (e.g. 'cli', 'web', 'mobile').
-	 * Override in subclass.
-	 *
-	 * @type {string}
-	 */
-	name = 'base'
+	constructor() {
+		/**
+		 * The name of this interface (e.g. 'cli', 'web', 'mobile').
+		 * Override in subclass.
+		 *
+		 * @type {string}
+		 */
+		this.name = 'base'
+	}
 
 	/**
 	 * Render data to the user through the interface.

package/src/Model/index.js

@@ -1,13 +1,65 @@
 import User from './User/User.js'
-import * as DomainModels from '../domain/index.js'
+import { HeaderModel } from '../domain/HeaderModel.js'
+import { FooterModel } from '../domain/FooterModel.js'
+import { HeroModel } from '../domain/HeroModel.js'
+import {
+	ButtonModel,
+	ConfirmModel,
+	InputModel,
+	SpinnerModel,
+	TableModel,
+	ToastModel,
+	SelectModel,
+	AutocompleteModel,
+	TreeModel,
+	TabsModel,
+	AccordionModel,
+	GalleryModel,
+	PriceModel,
+	PricingModel,
+	CommentModel,
+	TestimonialModel,
+	StatsItemModel,
+	StatsModel,
+	TimelineItemModel,
+	TimelineModel,
+	EmptyStateModel,
+	BannerModel,
+	ProfileDropdownModel,
+} from '../domain/components/index.js'
 
-const Model = {
+export {
 	User,
-	...DomainModels,
+	HeaderModel,
+	FooterModel,
+	HeroModel,
+	ButtonModel,
+	ConfirmModel,
+	InputModel,
+	SpinnerModel,
+	TableModel,
+	ToastModel,
+	SelectModel,
+	AutocompleteModel,
+	TreeModel,
+	TabsModel,
+	AccordionModel,
+	GalleryModel,
+	PriceModel,
+	PricingModel,
+	CommentModel,
+	TestimonialModel,
+	StatsItemModel,
+	StatsModel,
+	TimelineItemModel,
+	TimelineModel,
+	EmptyStateModel,
+	BannerModel,
+	ProfileDropdownModel,
 }
 
-export { User }
-export const {
+const Model = {
+	User,
 	HeaderModel,
 	FooterModel,
 	HeroModel,
@@ -31,6 +83,9 @@ export const {
 	StatsModel,
 	TimelineItemModel,
 	TimelineModel,
-} = DomainModels
+	EmptyStateModel,
+	BannerModel,
+	ProfileDropdownModel,
+}
 
 export default Model

package/src/StdIn.js

@@ -14,12 +14,6 @@ export default class StdIn extends EventProcessor {
 	/** @type {string[]} Messages to ignore */
 	static IGNORE_MESSAGES = ['', 'undefined']
 
-	/** @type {UiMessage[]} Input message buffer */
-	stream = []
-
-	/** @type {Processor} Input processor */
-	processor
-
 	/**
 	 * Creates a new StdIn instance.
 	 * @param {object} props - StdIn properties
@@ -29,7 +23,9 @@ export default class StdIn extends EventProcessor {
 	constructor(props = {}) {
 		super()
 		const { processor = new Processor(), stream = [] } = props
+		/** @type {Processor} Input processor */
 		this.processor = processor
+		/** @type {UiMessage[]} Input message buffer */
 		this.stream = stream
 		this.processor?.on('data', (data) => {
 			this.write(data)

package/src/cli.js

@@ -0,0 +1 @@
+export { UIApp as default } from './domain/app/UIApp.js'

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,12 @@ 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]
@@ -37,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.
  */
 
 /**
@@ -53,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)
 			},
 		)
@@ -105,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
@@ -140,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': {
@@ -167,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)
@@ -182,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)
@@ -200,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)
@@ -216,6 +247,35 @@ export async function runGenerator(generator, handlers, options = {}) {
 				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