@intent-framework/core 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mahyar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/act.d.ts

@@ -0,0 +1,49 @@
+import { type Condition } from "./signal.js";
+export type NavigationService = (name: string, params?: Record<string, string>) => void;
+export type DefaultScreenServices = {
+    navigate?: NavigationService;
+};
+export type ActionExecutionContext<TServices extends object = DefaultScreenServices> = Readonly<TServices>;
+export type FeedbackConfig = {
+    pending?: string;
+    success?: string;
+    failure?: string | ((error: Error) => string);
+};
+export type ActStatus = "idle" | "pending" | "success" | "failure";
+export type ActCondition = {
+    check: () => boolean;
+    message?: string;
+    source?: Condition;
+};
+export declare const kResourceMap: unique symbol;
+export type ActNode<TServices extends object = DefaultScreenServices> = {
+    id: string;
+    label: string;
+    primary: boolean;
+    conditions: ActCondition[];
+    handler: ((context: ActionExecutionContext<TServices>) => Promise<void> | void) | null;
+    feedback?: FeedbackConfig;
+    invalidatedResourceIds: string[];
+    status: ActStatus;
+    statusMessage: string | null;
+    enabled: Condition;
+    blockedReasons: string[];
+    execute: (context?: ActionExecutionContext<TServices>) => Promise<void>;
+    onStatusChange: (fn: () => void) => () => void;
+};
+export declare function createActNode<TServices extends object = DefaultScreenServices>(id: string, label: string, conditions: ActCondition[], handler: ((context: ActionExecutionContext<TServices>) => Promise<void> | void) | null, feedback: FeedbackConfig | undefined, primary: boolean, invalidatedResourceIds?: string[]): ActNode<TServices>;
+export declare class ActBuilder<TServices extends object = DefaultScreenServices> {
+    private node;
+    constructor(label: string);
+    get enabled(): Condition;
+    primary(): this;
+    when(condition: Condition | boolean | (() => boolean) | {
+        valid?: Condition | boolean;
+    }, message?: string): this;
+    does(fn: (context: ActionExecutionContext<TServices>) => Promise<void> | void): this;
+    invalidates(...resources: {
+        id: string;
+    }[]): this;
+    feedback(fb: FeedbackConfig): this;
+    toNode(): ActNode<TServices>;
+}

package/dist/ask.d.ts

@@ -0,0 +1,39 @@
+import { type Condition } from "./signal.js";
+export type AskKind = "text" | "contact" | "secret" | "choice";
+export type AskNode<T> = {
+    id: string;
+    label: string;
+    kind: AskKind;
+    contactKind?: string;
+    required: boolean;
+    requiredMessage?: string;
+    isPrivate: boolean;
+    hintText?: string;
+    validators: Array<(value: T) => string | boolean>;
+    state: {
+        value: T;
+    };
+    valid: Condition;
+    error: string | null;
+    subscribe: (fn: () => void) => () => void;
+};
+export type AnyAskNode = AskNode<unknown>;
+export declare function createAskNode<T>(id: string, label: string, stateRef: {
+    value: T;
+}, notifySub?: (fn: () => void) => () => void): AskNode<T>;
+export declare class AskBuilder<T> {
+    private node;
+    constructor(label: string, stateRef: {
+        value: T;
+        onChange?: (fn: (value: T) => void) => () => void;
+    });
+    get valid(): Condition;
+    asContact(kind: string): this;
+    asSecret(): this;
+    asChoice(): this;
+    required(message?: string): this;
+    validate(fn: (value: T) => string | boolean): this;
+    private(): this;
+    hint(text: string): this;
+    toNode(): AskNode<T>;
+}

package/dist/flow.d.ts

@@ -0,0 +1,23 @@
+import type { AnyAskNode } from "./ask.js";
+import type { ActNode } from "./act.js";
+import { AskBuilder } from "./ask.js";
+import { ActBuilder } from "./act.js";
+export type FlowStep = {
+    type: "ask";
+    node: AnyAskNode;
+} | {
+    type: "act";
+    node: ActNode;
+};
+export type FlowNode = {
+    id: string;
+    name: string;
+    steps: FlowStep[];
+};
+export declare class FlowBuilder {
+    private node;
+    constructor(name: string);
+    startsWith(ask: AnyAskNode | AskBuilder<any>): this;
+    then(item: AnyAskNode | ActNode | AskBuilder<any> | ActBuilder<any>): this;
+    toNode(): FlowNode;
+}

package/dist/graph.d.ts

@@ -0,0 +1,52 @@
+import type { ScreenDefinition } from "./screen.js";
+import type { DefaultScreenServices } from "./act.js";
+import type { AnyResourceNode } from "./resource.js";
+export type DiagnosticSeverity = "info" | "warning" | "error";
+export type GraphDiagnostic = {
+    severity: DiagnosticSeverity;
+    code: string;
+    message: string;
+    nodeId?: string;
+};
+export type InspectedScreen = {
+    name: string;
+    asks: Array<{
+        id: string;
+        label: string;
+        kind: string;
+        required: boolean;
+        isPrivate: boolean;
+        valid: boolean;
+        error: string | null;
+    }>;
+    acts: Array<{
+        id: string;
+        label: string;
+        primary: boolean;
+        enabled: boolean;
+        blockedReasons: string[];
+        status: string;
+        statusMessage: string | null;
+        invalidates: string[];
+    }>;
+    flows: Array<{
+        id: string;
+        name: string;
+        stepCount: number;
+    }>;
+    surfaces: Array<{
+        id: string;
+        name: string;
+        itemCount: number;
+    }>;
+    resources: Array<{
+        id: string;
+        name: string;
+        status: string;
+        hasValue: boolean;
+        stale: boolean;
+        error: string | undefined;
+    }>;
+    diagnostics: GraphDiagnostic[];
+};
+export declare function inspectScreen<TServices extends object = DefaultScreenServices>(screenDef: ScreenDefinition<TServices>, runtimeResources?: AnyResourceNode[]): InspectedScreen;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { screen } from "./screen.js";
+export type { ScreenDefinition, ScreenBuilder } from "./screen.js";
+export { inspectScreen } from "./graph.js";
+export type { InspectedScreen, GraphDiagnostic, DiagnosticSeverity } from "./graph.js";
+export type { TextState, BooleanState, ChoiceState } from "./state.js";
+export type { AskNode, AnyAskNode, AskKind, AskBuilder } from "./ask.js";
+export type { ActNode, ActCondition, ActStatus, FeedbackConfig, ActBuilder, NavigationService, ActionExecutionContext, DefaultScreenServices } from "./act.js";
+export type { FlowNode, FlowStep, FlowBuilder } from "./flow.js";
+export type { SurfaceNode, SurfaceBuilder } from "./surface.js";
+export type { ResourceNode, ResourceConfig, ResourceLoadContext, ResourceStatus, AnyResourceNode } from "./resource.js";
+export { ResourceRef, createResourceNode } from "./resource.js";
+export { createScreenRuntime } from "./runtime.js";
+export type { ScreenRuntime } from "./runtime.js";
+export { resetAskRegistry, resetActRegistry, resetFlowRegistry, resetSurfaceRegistry, resetResourceRegistry, getAsks, getActs, getFlows, getSurfaces, getResources, } from "./registry.js";
+export type { Condition } from "./signal.js";
+export { isCondition } from "./signal.js";

package/dist/index.js

@@ -0,0 +1,854 @@
+//#region src/signal.ts
+function isCondition(value) {
+	return typeof value === "object" && value !== null && "current" in value && "subscribe" in value;
+}
+function createCondition(compute, subscribeToChanges, reason) {
+	return {
+		get current() {
+			return compute();
+		},
+		reason,
+		subscribe(fn) {
+			return subscribeToChanges(() => fn());
+		}
+	};
+}
+function signal(initial) {
+	let value = initial;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		get() {
+			return value;
+		},
+		set(newValue) {
+			if (newValue !== value) {
+				value = newValue;
+				for (const fn of listeners) fn(value);
+			}
+		},
+		subscribe(fn) {
+			listeners.add(fn);
+			return () => {
+				listeners.delete(fn);
+			};
+		}
+	};
+}
+
+//#endregion
+//#region src/resource.ts
+function createResourceNode(id, name, loader, autoLoad = true) {
+	const statusSignal = signal(0);
+	const staleSignal = signal(0);
+	let currentStatus = "idle";
+	let currentValue = void 0;
+	let currentError = void 0;
+	let currentStale = false;
+	let lastContext = void 0;
+	const notify = () => statusSignal.set(statusSignal.get() + 1);
+	const staleNotify = () => staleSignal.set(staleSignal.get() + 1);
+	let _ready;
+	let _pending;
+	let _failed;
+	let _stale;
+	function getReady() {
+		if (!_ready) _ready = createCondition(() => currentStatus === "ready", (notify$1) => statusSignal.subscribe(() => notify$1()));
+		return _ready;
+	}
+	function getPending() {
+		if (!_pending) _pending = createCondition(() => currentStatus === "pending", (notify$1) => statusSignal.subscribe(() => notify$1()));
+		return _pending;
+	}
+	function getFailed() {
+		if (!_failed) _failed = createCondition(() => currentStatus === "failed", (notify$1) => statusSignal.subscribe(() => notify$1()));
+		return _failed;
+	}
+	function getStale() {
+		if (!_stale) _stale = createCondition(() => currentStale, (notify$1) => staleSignal.subscribe(() => notify$1()));
+		return _stale;
+	}
+	async function executeLoad(context) {
+		currentStale = false;
+		staleNotify();
+		currentStatus = "pending";
+		currentValue = void 0;
+		currentError = void 0;
+		notify();
+		if (context !== void 0) lastContext = context;
+		const loadContext = context ?? lastContext ?? {};
+		try {
+			const result = await Promise.resolve(loader(loadContext));
+			currentValue = result;
+			currentStatus = "ready";
+			currentStale = false;
+			notify();
+			staleNotify();
+		} catch (e) {
+			currentError = e;
+			currentStatus = "failed";
+			currentStale = false;
+			notify();
+			staleNotify();
+		}
+	}
+	function invalidate() {
+		if (!currentStale) {
+			currentStale = true;
+			staleNotify();
+		}
+	}
+	const node = {
+		id,
+		name,
+		autoLoad,
+		get status() {
+			return currentStatus;
+		},
+		get value() {
+			return currentValue;
+		},
+		get error() {
+			return currentError;
+		},
+		get ready() {
+			return getReady();
+		},
+		get pending() {
+			return getPending();
+		},
+		get failed() {
+			return getFailed();
+		},
+		get stale() {
+			return getStale();
+		},
+		load: executeLoad,
+		reload: executeLoad,
+		invalidate,
+		subscribe(fn) {
+			return statusSignal.subscribe(fn);
+		}
+	};
+	return node;
+}
+var ResourceRef = class {
+	id;
+	name;
+	autoLoad;
+	loader;
+	_connected = null;
+	_connSignal = signal(0);
+	_nodeSub = null;
+	_readyCache;
+	_pendingCache;
+	_failedCache;
+	_staleCache;
+	constructor(id, name, loader, autoLoad) {
+		this.id = id;
+		this.name = name;
+		this.loader = loader;
+		this.autoLoad = autoLoad;
+	}
+	get status() {
+		return this._connected?.status ?? "idle";
+	}
+	get value() {
+		return this._connected?.value;
+	}
+	get error() {
+		return this._connected?.error;
+	}
+	get ready() {
+		if (!this._readyCache) this._readyCache = createCondition(() => this._connected?.status === "ready", (notify) => {
+			const unsubs = [];
+			unsubs.push(this._connSignal.subscribe(notify));
+			const node = this._connected;
+			if (node) unsubs.push(node.ready.subscribe(notify));
+			return () => {
+				for (const u of unsubs) u();
+			};
+		});
+		return this._readyCache;
+	}
+	get pending() {
+		if (!this._pendingCache) this._pendingCache = createCondition(() => this._connected?.status === "pending", (notify) => {
+			const unsubs = [];
+			unsubs.push(this._connSignal.subscribe(notify));
+			const node = this._connected;
+			if (node) unsubs.push(node.pending.subscribe(notify));
+			return () => {
+				for (const u of unsubs) u();
+			};
+		});
+		return this._pendingCache;
+	}
+	get failed() {
+		if (!this._failedCache) this._failedCache = createCondition(() => this._connected?.status === "failed", (notify) => {
+			const unsubs = [];
+			unsubs.push(this._connSignal.subscribe(notify));
+			const node = this._connected;
+			if (node) unsubs.push(node.failed.subscribe(notify));
+			return () => {
+				for (const u of unsubs) u();
+			};
+		});
+		return this._failedCache;
+	}
+	get stale() {
+		if (!this._staleCache) this._staleCache = createCondition(() => this._connected?.stale.current ?? false, (notify) => {
+			const unsubs = [];
+			unsubs.push(this._connSignal.subscribe(notify));
+			const node = this._connected;
+			if (node) unsubs.push(node.stale.subscribe(notify));
+			return () => {
+				for (const u of unsubs) u();
+			};
+		});
+		return this._staleCache;
+	}
+	load(context) {
+		return this._connected?.load(context) ?? Promise.resolve();
+	}
+	reload(context) {
+		return this._connected?.reload(context) ?? Promise.resolve();
+	}
+	invalidate() {
+		this._connected?.invalidate();
+	}
+	subscribe(fn) {
+		return this._connSignal.subscribe(fn);
+	}
+	_connect(node) {
+		this._disconnect();
+		this._connected = node;
+		this._nodeSub = node.subscribe(() => {
+			this._connSignal.set(this._connSignal.get() + 1);
+		});
+		this._connSignal.set(this._connSignal.get() + 1);
+	}
+	_disconnect(expectedNode) {
+		if (expectedNode && this._connected !== expectedNode) return;
+		this._nodeSub?.();
+		this._nodeSub = null;
+		this._connected = null;
+		this._connSignal.set(this._connSignal.get() + 1);
+	}
+};
+
+//#endregion
+//#region src/state.ts
+function createTextState(_name, initial = "") {
+	const sig = signal(initial);
+	const validCondition = createCondition(() => sig.get().length > 0, (notify) => sig.subscribe(() => notify()));
+	return {
+		get value() {
+			return sig.get();
+		},
+		get valid() {
+			return validCondition;
+		},
+		set(value) {
+			sig.set(value);
+		},
+		onChange(fn) {
+			return sig.subscribe(fn);
+		},
+		clear() {
+			sig.set("");
+		}
+	};
+}
+function createBooleanState(_name, initial = false) {
+	const sig = signal(initial);
+	const validCondition = createCondition(() => true, (notify) => sig.subscribe(() => notify()));
+	return {
+		get value() {
+			return sig.get();
+		},
+		get valid() {
+			return validCondition;
+		},
+		set(value) {
+			sig.set(value);
+		},
+		toggle() {
+			sig.set(!sig.get());
+		},
+		onChange(fn) {
+			return sig.subscribe(fn);
+		}
+	};
+}
+function createChoiceState(_name, opts) {
+	if (!opts.options.includes(opts.initial)) throw new Error(`state.choice initial value "${opts.initial}" must be one of the provided options`);
+	const sig = signal(opts.initial);
+	const validCondition = createCondition(() => opts.options.includes(sig.get()), (notify) => sig.subscribe(() => notify()));
+	return {
+		get value() {
+			return sig.get();
+		},
+		get valid() {
+			return validCondition;
+		},
+		set(value) {
+			sig.set(value);
+		},
+		get options() {
+			return opts.options;
+		},
+		onChange(fn) {
+			return sig.subscribe(fn);
+		}
+	};
+}
+
+//#endregion
+//#region src/registry.ts
+const askMap = /* @__PURE__ */ new Map();
+const actMap = /* @__PURE__ */ new Map();
+const flowMap = /* @__PURE__ */ new Map();
+const surfaceMap = /* @__PURE__ */ new Map();
+const resourceMap = /* @__PURE__ */ new Map();
+function registerAskNode(node) {
+	askMap.set(node.id, node);
+}
+function registerActNode(node) {
+	actMap.set(node.id, node);
+}
+function registerFlowNode(node) {
+	flowMap.set(node.id, node);
+}
+function registerSurfaceNode(node) {
+	surfaceMap.set(node.id, node);
+}
+function resetAskRegistry() {
+	askMap.clear();
+}
+function resetActRegistry() {
+	actMap.clear();
+}
+function resetFlowRegistry() {
+	flowMap.clear();
+}
+function resetSurfaceRegistry() {
+	surfaceMap.clear();
+}
+function resetResourceRegistry() {
+	resourceMap.clear();
+}
+function getAsks() {
+	return askMap;
+}
+function getActs() {
+	return actMap;
+}
+function getFlows() {
+	return flowMap;
+}
+function getSurfaces() {
+	return surfaceMap;
+}
+function getResources() {
+	return resourceMap;
+}
+
+//#endregion
+//#region src/ask.ts
+function createAskNode(id, label, stateRef, notifySub) {
+	const notifySignal = signal(0);
+	notifySub?.(() => {
+		notifySignal.set(notifySignal.get() + 1);
+	});
+	const validCondition = {
+		get current() {
+			return computeAskValidity(node);
+		},
+		subscribe(fn) {
+			return notifySignal.subscribe(() => fn());
+		}
+	};
+	const node = {
+		id,
+		label,
+		kind: "text",
+		required: false,
+		isPrivate: false,
+		validators: [],
+		state: stateRef,
+		get valid() {
+			return validCondition;
+		},
+		get error() {
+			return computeAskError(node);
+		},
+		subscribe(fn) {
+			return notifySignal.subscribe(fn);
+		}
+	};
+	return node;
+}
+function computeAskValidity(node) {
+	const value = node.state.value;
+	if (node.required && (value === "" || value === void 0 || value === null)) return false;
+	for (const validator of node.validators) {
+		const result = validator(value);
+		if (result !== true) return false;
+	}
+	return true;
+}
+function computeAskError(node) {
+	const value = node.state.value;
+	if (node.required && (value === "" || value === void 0 || value === null)) return node.requiredMessage ?? "This field is required.";
+	for (const validator of node.validators) {
+		const result = validator(value);
+		if (result !== true) return typeof result === "string" ? result : "Invalid value.";
+	}
+	return null;
+}
+var AskBuilder = class {
+	node;
+	constructor(label, stateRef) {
+		const id = `ask_${label.toLowerCase().replace(/\s+/g, "_")}`;
+		const onChange = stateRef.onChange;
+		const subscribeToState = onChange ? (fn) => onChange((_v) => fn()) : void 0;
+		this.node = createAskNode(id, label, stateRef, subscribeToState);
+		registerAskNode(this.node);
+	}
+	get valid() {
+		return this.node.valid;
+	}
+	asContact(kind) {
+		this.node.kind = "contact";
+		this.node.contactKind = kind;
+		return this;
+	}
+	asSecret() {
+		this.node.kind = "secret";
+		return this;
+	}
+	asChoice() {
+		this.node.kind = "choice";
+		return this;
+	}
+	required(message) {
+		this.node.required = true;
+		this.node.requiredMessage = message;
+		return this;
+	}
+	validate(fn) {
+		this.node.validators.push(fn);
+		return this;
+	}
+	private() {
+		this.node.isPrivate = true;
+		return this;
+	}
+	hint(text) {
+		this.node.hintText = text;
+		return this;
+	}
+	toNode() {
+		return this.node;
+	}
+};
+
+//#endregion
+//#region src/act.ts
+const kResourceMap = Symbol("resourceMap");
+function createActNode(id, label, conditions, handler, feedback, primary, invalidatedResourceIds = []) {
+	const statusSignal = signal(0);
+	const notifyStatus = () => statusSignal.set(statusSignal.get() + 1);
+	let _enabledCondition;
+	function getEnabledCondition() {
+		if (!_enabledCondition) _enabledCondition = createCondition(() => computeActEnabled(node), (notify) => {
+			const unsubs = node.conditions.filter((c) => c.source).map((c) => c.source.subscribe(() => notify()));
+			return () => {
+				for (const u of unsubs) u();
+			};
+		});
+		return _enabledCondition;
+	}
+	const node = {
+		id,
+		label,
+		primary,
+		conditions,
+		handler,
+		feedback,
+		invalidatedResourceIds,
+		status: "idle",
+		statusMessage: null,
+		get enabled() {
+			return getEnabledCondition();
+		},
+		get blockedReasons() {
+			return node.conditions.filter((c) => !c.check()).map((c) => c.message).filter((m) => m !== void 0);
+		},
+		execute: async (context) => {
+			await executeAct(node, context, notifyStatus);
+		},
+		onStatusChange(fn) {
+			return statusSignal.subscribe(fn);
+		}
+	};
+	return node;
+}
+function computeActEnabled(node) {
+	for (const cond of node.conditions) if (!cond.check()) return false;
+	return true;
+}
+async function executeAct(node, context, notify) {
+	if (!node.enabled.current || !node.handler) return;
+	node.status = "pending";
+	node.statusMessage = node.feedback?.pending ?? null;
+	notify();
+	try {
+		await node.handler(context ?? {});
+		node.status = "success";
+		node.statusMessage = node.feedback?.success ?? null;
+		notify();
+		const resourceMap$1 = context ? context[kResourceMap] : void 0;
+		if (resourceMap$1) for (const id of node.invalidatedResourceIds) resourceMap$1.get(id)?.invalidate();
+	} catch (error) {
+		node.status = "failure";
+		const fb = node.feedback?.failure;
+		if (typeof fb === "function") node.statusMessage = fb(error instanceof Error ? error : new Error(String(error)));
+		else node.statusMessage = fb ?? null;
+		notify();
+	}
+}
+var ActBuilder = class {
+	node;
+	constructor(label) {
+		const id = `act_${label.toLowerCase().replace(/\s+/g, "_")}`;
+		this.node = createActNode(id, label, [], null, void 0, false);
+		registerActNode(this.node);
+	}
+	get enabled() {
+		return this.node.enabled;
+	}
+	primary() {
+		this.node.primary = true;
+		return this;
+	}
+	when(condition, message) {
+		let check;
+		let source;
+		if (typeof condition === "function") check = condition;
+		else if (typeof condition === "object" && condition !== null && "valid" in condition) {
+			const state = condition;
+			if (state.valid !== void 0 && isCondition(state.valid)) {
+				const cond = state.valid;
+				source = cond;
+				check = () => cond.current;
+			} else if (state.valid !== void 0) {
+				const val = state.valid;
+				check = () => val;
+			} else check = () => false;
+		} else if (isCondition(condition)) {
+			source = condition;
+			check = () => condition.current;
+		} else check = () => condition;
+		this.node.conditions.push({
+			check,
+			message,
+			source
+		});
+		return this;
+	}
+	does(fn) {
+		this.node.handler = fn;
+		return this;
+	}
+	invalidates(...resources) {
+		this.node.invalidatedResourceIds = resources.map((r) => r.id);
+		return this;
+	}
+	feedback(fb) {
+		this.node.feedback = fb;
+		return this;
+	}
+	toNode() {
+		return this.node;
+	}
+};
+
+//#endregion
+//#region src/flow.ts
+var FlowBuilder = class {
+	node;
+	constructor(name) {
+		const id = `flow_${name}`;
+		this.node = {
+			id,
+			name,
+			steps: []
+		};
+		registerFlowNode(this.node);
+	}
+	startsWith(ask) {
+		const node = ask instanceof AskBuilder ? ask.toNode() : ask;
+		this.node.steps.push({
+			type: "ask",
+			node
+		});
+		return this;
+	}
+	then(item) {
+		if (item instanceof ActBuilder) this.node.steps.push({
+			type: "act",
+			node: item.toNode()
+		});
+		else if (item instanceof AskBuilder) this.node.steps.push({
+			type: "ask",
+			node: item.toNode()
+		});
+		else if ("validators" in item) this.node.steps.push({
+			type: "ask",
+			node: item
+		});
+		else this.node.steps.push({
+			type: "act",
+			node: item
+		});
+		return this;
+	}
+	toNode() {
+		return this.node;
+	}
+};
+
+//#endregion
+//#region src/surface.ts
+var SurfaceBuilder = class {
+	node;
+	constructor(name) {
+		const id = `surface_${name}`;
+		this.node = {
+			id,
+			name,
+			items: []
+		};
+		registerSurfaceNode(this.node);
+	}
+	contains(...items) {
+		for (const item of items) if (item instanceof ActBuilder) this.node.items.push(item.toNode());
+		else if (item instanceof AskBuilder) this.node.items.push(item.toNode());
+		else this.node.items.push(item);
+		return this;
+	}
+	toNode() {
+		return this.node;
+	}
+};
+
+//#endregion
+//#region src/screen.ts
+function screen(name, fn) {
+	resetAskRegistry();
+	resetActRegistry();
+	resetFlowRegistry();
+	resetSurfaceRegistry();
+	resetResourceRegistry();
+	const configs = [];
+	const builder = {
+		state: {
+			text: (n, opts) => createTextState(n, opts?.initial),
+			boolean: (n, opts) => createBooleanState(n, opts?.initial),
+			choice: (n, opts) => createChoiceState(n, opts)
+		},
+		ask: (label, state) => new AskBuilder(label, state),
+		act: (label) => new ActBuilder(label),
+		flow: (n) => new FlowBuilder(n),
+		surface: (n) => new SurfaceBuilder(n),
+		resource: (n, config) => {
+			const id = `resource_${n}`;
+			const ref = new ResourceRef(id, n, config.load, config.autoLoad ?? true);
+			configs.push({
+				id,
+				name: n,
+				autoLoad: config.autoLoad ?? true,
+				loader: config.load,
+				ref
+			});
+			return ref;
+		}
+	};
+	fn(builder);
+	const asks = getAsks();
+	const acts = getActs();
+	const flows = getFlows();
+	const surfaces = getSurfaces();
+	return {
+		name,
+		asks: Array.from(asks.values()),
+		acts: Array.from(acts.values()),
+		flows: Array.from(flows.values()),
+		surfaces: Array.from(surfaces.values()),
+		resourceConfigs: configs
+	};
+}
+
+//#endregion
+//#region src/graph.ts
+function computeDiagnostics(screenDef) {
+	const diagnostics = [];
+	const primaryActions = screenDef.acts.filter((a) => a.primary);
+	if (primaryActions.length > 1) diagnostics.push({
+		severity: "warning",
+		code: "multiple-primary-actions",
+		message: "Screen has multiple primary actions, so default action behavior is ambiguous."
+	});
+	for (const ask of screenDef.asks) if (ask.kind === "secret" && !ask.isPrivate) diagnostics.push({
+		severity: "warning",
+		code: "secret-ask-not-private",
+		message: "Secret ask should also be marked private.",
+		nodeId: ask.id
+	});
+	for (const act of screenDef.acts) if (act.primary && act.conditions.length > 0 && act.conditions.every((c) => c.message === void 0)) diagnostics.push({
+		severity: "info",
+		code: "primary-action-without-blocked-reason",
+		message: "Primary action can be blocked without an explainable reason.",
+		nodeId: act.id
+	});
+	const surfacedNodeIds = /* @__PURE__ */ new Set();
+	for (const surface of screenDef.surfaces) for (const item of surface.items) surfacedNodeIds.add(item.id);
+	for (const ask of screenDef.asks) if (!surfacedNodeIds.has(ask.id)) diagnostics.push({
+		severity: "warning",
+		code: "ask-not-in-surface",
+		message: "Ask is defined but not included in any surface.",
+		nodeId: ask.id
+	});
+	for (const act of screenDef.acts) if (!surfacedNodeIds.has(act.id)) diagnostics.push({
+		severity: "warning",
+		code: "action-not-in-surface",
+		message: "Action is defined but not included in any surface.",
+		nodeId: act.id
+	});
+	return diagnostics;
+}
+function inspectScreen(screenDef, runtimeResources) {
+	return {
+		name: screenDef.name,
+		asks: screenDef.asks.map((a) => ({
+			id: a.id,
+			label: a.label,
+			kind: a.kind,
+			required: a.required,
+			isPrivate: a.isPrivate,
+			valid: a.valid.current,
+			error: a.error
+		})),
+		acts: screenDef.acts.map((a) => ({
+			id: a.id,
+			label: a.label,
+			primary: a.primary,
+			enabled: a.enabled.current,
+			blockedReasons: a.blockedReasons,
+			status: a.status,
+			statusMessage: a.statusMessage,
+			invalidates: a.invalidatedResourceIds
+		})),
+		flows: screenDef.flows.map((f) => ({
+			id: f.id,
+			name: f.name,
+			stepCount: f.steps.length
+		})),
+		surfaces: screenDef.surfaces.map((s) => ({
+			id: s.id,
+			name: s.name,
+			itemCount: s.items.length
+		})),
+		resources: (runtimeResources ?? []).map((r) => ({
+			id: r.id,
+			name: r.name,
+			status: r.status,
+			hasValue: r.value !== void 0,
+			stale: r.stale.current,
+			error: r.status === "failed" ? r.error instanceof Error ? r.error.message : String(r.error) : void 0
+		})),
+		diagnostics: computeDiagnostics(screenDef)
+	};
+}
+
+//#endregion
+//#region src/runtime.ts
+var ScreenRuntime = class {
+	_screen;
+	_started = false;
+	_disposed = false;
+	_unsubscribers = [];
+	_services;
+	_resourceNodes = [];
+	_resourceNodeMap = null;
+	autoloadedResources = /* @__PURE__ */ new Set();
+	constructor(screen$1, services = {}) {
+		this._screen = screen$1;
+		this._services = services;
+	}
+	get screen() {
+		return this._screen;
+	}
+	get graph() {
+		return inspectScreen(this._screen, this._resourceNodes);
+	}
+	get resources() {
+		return this._resourceNodes;
+	}
+	get services() {
+		return this._services;
+	}
+	getExecutionContext() {
+		return this._services;
+	}
+	executeAct(act, context) {
+		const ctx = context ?? this.getExecutionContext();
+		if (this._resourceNodeMap) return act.execute({
+			...ctx,
+			[kResourceMap]: this._resourceNodeMap
+		});
+		return act.execute(ctx);
+	}
+	async start() {
+		if (this._started) return;
+		this._started = true;
+		const nodeMap = /* @__PURE__ */ new Map();
+		for (const config of this._screen.resourceConfigs) {
+			const node = createResourceNode(config.id, config.name, config.loader, false);
+			this._resourceNodes.push(node);
+			nodeMap.set(config.id, node);
+		}
+		this._resourceNodeMap = nodeMap;
+		for (const config of this._screen.resourceConfigs) {
+			const node = nodeMap.get(config.id);
+			if (node && config.ref) config.ref._connect(node);
+		}
+		const pureServices = this._services;
+		const toLoad = this._resourceNodes.filter((r) => {
+			const config = this._screen.resourceConfigs.find((c) => c.id === r.id);
+			return (config?.autoLoad ?? false) && !this.autoloadedResources.has(r.id);
+		});
+		for (const r of toLoad) this.autoloadedResources.add(r.id);
+		if (toLoad.length > 0) await Promise.all(toLoad.map((r) => r.load(pureServices)));
+	}
+	dispose() {
+		if (this._disposed) return;
+		this._disposed = true;
+		for (const unsub of this._unsubscribers) unsub();
+		this._unsubscribers = [];
+		for (const config of this._screen.resourceConfigs) if (config.ref && this._resourceNodeMap) {
+			const node = this._resourceNodeMap.get(config.id);
+			if (node) config.ref._disconnect(node);
+		}
+	}
+	/** @internal */
+	_addUnsubscriber(fn) {
+		this._unsubscribers.push(fn);
+	}
+};
+function createScreenRuntime(screen$1, options) {
+	return new ScreenRuntime(screen$1, options?.services);
+}
+
+//#endregion
+export { ResourceRef, createResourceNode, createScreenRuntime, getActs, getAsks, getFlows, getResources, getSurfaces, inspectScreen, isCondition, resetActRegistry, resetAskRegistry, resetFlowRegistry, resetResourceRegistry, resetSurfaceRegistry, screen };

package/dist/registry.d.ts

@@ -0,0 +1,25 @@
+import type { AnyAskNode } from "./ask.js";
+import type { ActNode, DefaultScreenServices } from "./act.js";
+import type { FlowNode } from "./flow.js";
+import type { SurfaceNode } from "./surface.js";
+import type { AnyResourceNode } from "./resource.js";
+export declare function registerAskNode(node: AnyAskNode): void;
+export declare function unregisterAskNode(id: string): void;
+export declare function registerActNode<TServices extends object = DefaultScreenServices>(node: ActNode<TServices>): void;
+export declare function unregisterActNode(id: string): void;
+export declare function registerFlowNode(node: FlowNode): void;
+export declare function unregisterFlowNode(id: string): void;
+export declare function registerSurfaceNode(node: SurfaceNode): void;
+export declare function unregisterSurfaceNode(id: string): void;
+export declare function registerResourceNode(node: AnyResourceNode): void;
+export declare function unregisterResourceNode(id: string): void;
+export declare function resetAskRegistry(): void;
+export declare function resetActRegistry(): void;
+export declare function resetFlowRegistry(): void;
+export declare function resetSurfaceRegistry(): void;
+export declare function resetResourceRegistry(): void;
+export declare function getAsks(): Map<string, AnyAskNode>;
+export declare function getActs(): Map<string, ActNode<any>>;
+export declare function getFlows(): Map<string, FlowNode>;
+export declare function getSurfaces(): Map<string, SurfaceNode>;
+export declare function getResources(): Map<string, AnyResourceNode>;

package/dist/resource.d.ts

@@ -0,0 +1,59 @@
+import { type Condition } from "./signal.js";
+import type { ActionExecutionContext, DefaultScreenServices } from "./act.js";
+export type ResourceStatus = "idle" | "pending" | "ready" | "failed";
+export type ResourceLoadContext<TServices extends object = DefaultScreenServices> = ActionExecutionContext<TServices>;
+type ResourceLoader<TValue, TServices extends object> = (() => TValue | Promise<TValue>) | ((context: ResourceLoadContext<TServices>) => TValue | Promise<TValue>);
+export type ResourceNode<TValue, TServices extends object = DefaultScreenServices> = {
+    id: string;
+    name: string;
+    autoLoad: boolean;
+    status: ResourceStatus;
+    value: TValue | undefined;
+    error: unknown | undefined;
+    ready: Condition;
+    pending: Condition;
+    failed: Condition;
+    stale: Condition;
+    load: (context?: ResourceLoadContext<TServices>) => Promise<void>;
+    reload: (context?: ResourceLoadContext<TServices>) => Promise<void>;
+    invalidate: () => void;
+    subscribe: (fn: () => void) => () => void;
+};
+export type AnyResourceNode = ResourceNode<unknown, any>;
+export type ResourceConfig<TValue = unknown, TServices extends object = DefaultScreenServices> = {
+    id: string;
+    name: string;
+    autoLoad: boolean;
+    loader: ResourceLoader<TValue, TServices>;
+    ref?: ResourceRef<TValue, TServices>;
+};
+export declare function createResourceConfig<TValue, TServices extends object = DefaultScreenServices>(id: string, name: string, loader: ResourceLoader<TValue, TServices>, autoLoad?: boolean): ResourceConfig<TValue, TServices>;
+export declare function createResourceNode<TValue, TServices extends object = DefaultScreenServices>(id: string, name: string, loader: ResourceLoader<TValue, TServices>, autoLoad?: boolean): ResourceNode<TValue, TServices>;
+export declare class ResourceRef<TValue, TServices extends object = DefaultScreenServices> {
+    readonly id: string;
+    readonly name: string;
+    readonly autoLoad: boolean;
+    readonly loader: ResourceLoader<TValue, TServices>;
+    private _connected;
+    private _connSignal;
+    private _nodeSub;
+    private _readyCache;
+    private _pendingCache;
+    private _failedCache;
+    private _staleCache;
+    constructor(id: string, name: string, loader: ResourceLoader<TValue, TServices>, autoLoad: boolean);
+    get status(): ResourceStatus;
+    get value(): TValue | undefined;
+    get error(): unknown | undefined;
+    get ready(): Condition;
+    get pending(): Condition;
+    get failed(): Condition;
+    get stale(): Condition;
+    load(context?: ResourceLoadContext<TServices>): Promise<void>;
+    reload(context?: ResourceLoadContext<TServices>): Promise<void>;
+    invalidate(): void;
+    subscribe(fn: () => void): () => void;
+    _connect(node: ResourceNode<TValue, TServices>): void;
+    _disconnect(expectedNode?: ResourceNode<TValue, TServices>): void;
+}
+export {};

package/dist/runtime.d.ts

@@ -0,0 +1,28 @@
+import type { ScreenDefinition } from "./screen.js";
+import { type InspectedScreen } from "./graph.js";
+import type { AnyResourceNode } from "./resource.js";
+import type { ActionExecutionContext, DefaultScreenServices, ActNode } from "./act.js";
+export declare class ScreenRuntime<TServices extends object = DefaultScreenServices> {
+    private _screen;
+    private _started;
+    private _disposed;
+    private _unsubscribers;
+    private _services;
+    private _resourceNodes;
+    private _resourceNodeMap;
+    private autoloadedResources;
+    constructor(screen: ScreenDefinition<TServices>, services?: TServices);
+    get screen(): ScreenDefinition<TServices>;
+    get graph(): InspectedScreen;
+    get resources(): AnyResourceNode[];
+    get services(): TServices;
+    getExecutionContext(): ActionExecutionContext<TServices>;
+    executeAct(act: ActNode<TServices>, context?: ActionExecutionContext<TServices>): Promise<void>;
+    start(): Promise<void>;
+    dispose(): void;
+    /** @internal */
+    _addUnsubscriber(fn: () => void): void;
+}
+export declare function createScreenRuntime<TServices extends object = DefaultScreenServices>(screen: ScreenDefinition<TServices>, options?: {
+    services?: TServices;
+}): ScreenRuntime<TServices>;

package/dist/screen.d.ts

@@ -0,0 +1,44 @@
+import type { AnyAskNode } from "./ask.js";
+import type { ActNode, DefaultScreenServices } from "./act.js";
+import type { FlowNode } from "./flow.js";
+import type { SurfaceNode } from "./surface.js";
+import type { ResourceConfig, ResourceLoadContext } from "./resource.js";
+import { ResourceRef } from "./resource.js";
+import { type TextState, type BooleanState, type ChoiceState } from "./state.js";
+import { AskBuilder } from "./ask.js";
+import { ActBuilder } from "./act.js";
+import { FlowBuilder } from "./flow.js";
+import { SurfaceBuilder } from "./surface.js";
+export type ScreenBuilder<TServices extends object = DefaultScreenServices> = {
+    state: {
+        text: (name: string, opts?: {
+            initial?: string;
+        }) => TextState;
+        boolean: (name: string, opts?: {
+            initial?: boolean;
+        }) => BooleanState;
+        choice: <T extends string>(name: string, opts: {
+            initial: T;
+            options: readonly T[];
+        }) => ChoiceState<T>;
+    };
+    ask: <T>(label: string, state: {
+        value: T;
+    }) => AskBuilder<T>;
+    act: (label: string) => ActBuilder<TServices>;
+    flow: (name: string) => FlowBuilder;
+    surface: (name: string) => SurfaceBuilder;
+    resource: <T>(name: string, config: {
+        load: (() => Promise<T>) | ((context: ResourceLoadContext<TServices>) => Promise<T>);
+        autoLoad?: boolean;
+    }) => ResourceRef<T, TServices>;
+};
+export type ScreenDefinition<TServices extends object = DefaultScreenServices> = {
+    name: string;
+    asks: AnyAskNode[];
+    acts: ActNode<TServices>[];
+    flows: FlowNode[];
+    surfaces: SurfaceNode[];
+    resourceConfigs: ResourceConfig[];
+};
+export declare function screen<TServices extends object = DefaultScreenServices>(name: string, fn: ($: ScreenBuilder<TServices>) => void): ScreenDefinition<TServices>;

package/dist/signal.d.ts

@@ -0,0 +1,21 @@
+export type Condition = {
+    readonly current: boolean;
+    readonly reason?: string;
+    subscribe(fn: () => void): () => void;
+};
+export declare function isCondition(value: unknown): value is Condition;
+export declare function createCondition(compute: () => boolean, subscribeToChanges: (onChange: () => void) => () => void, reason?: string): Condition;
+export type Signal<T> = {
+    get(): T;
+    set(value: T): void;
+    subscribe(fn: (value: T) => void): () => void;
+};
+export declare function signal<T>(initial: T): Signal<T>;
+export type Computed<T> = {
+    get(): T;
+    subscribe(fn: (value: T) => void): () => void;
+};
+export declare function derive<T>(dependencies: Array<{
+    subscribe: (fn: (...args: unknown[]) => void) => () => void;
+    get(): unknown;
+}>, compute: () => T): Computed<T>;

package/dist/state.d.ts

@@ -0,0 +1,28 @@
+import { type Condition } from "./signal.js";
+export interface TextState {
+    value: string;
+    valid: Condition;
+    set(value: string): void;
+    onChange(fn: (value: string) => void): () => void;
+    clear(): void;
+}
+export interface BooleanState {
+    value: boolean;
+    valid: Condition;
+    set(value: boolean): void;
+    toggle(): void;
+    onChange(fn: (value: boolean) => void): () => void;
+}
+export interface ChoiceState<T extends string> {
+    value: T;
+    valid: Condition;
+    set(value: T): void;
+    options: readonly T[];
+    onChange(fn: (value: T) => void): () => void;
+}
+export declare function createTextState(_name: string, initial?: string): TextState;
+export declare function createBooleanState(_name: string, initial?: boolean): BooleanState;
+export declare function createChoiceState<T extends string>(_name: string, opts: {
+    initial: T;
+    options: readonly T[];
+}): ChoiceState<T>;

package/dist/surface.d.ts

@@ -0,0 +1,15 @@
+import type { AnyAskNode } from "./ask.js";
+import type { ActNode } from "./act.js";
+import { AskBuilder } from "./ask.js";
+import { ActBuilder } from "./act.js";
+export type SurfaceNode = {
+    id: string;
+    name: string;
+    items: Array<AnyAskNode | ActNode>;
+};
+export declare class SurfaceBuilder {
+    private node;
+    constructor(name: string);
+    contains(...items: Array<AnyAskNode | ActNode | AskBuilder<any> | ActBuilder<any>>): this;
+    toNode(): SurfaceNode;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@intent-framework/core",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.1.0-alpha.0",
+  "description": "Platformless semantic graph and runtime for Intent applications",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/intent-framework/intent.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsdown": "^0.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc -b",
+    "lint": "tsc -b"
+  }
+}