diff --git a/.fas/TASKS.md b/.fas/TASKS.md index b6e9760f..f1d57e00 100644 --- a/.fas/TASKS.md +++ b/.fas/TASKS.md @@ -2121,17 +2121,23 @@ No active tasks. - Title: docs: add Ignite Element for AI Agents one-pager before v3 stable - Mode: single-agent -- Status: backlog -- Owner: planner +- Status: done +- Owner: implementer - Brief: .fas/tasks/docs-add-ignite-element-for-ai-agents-one-pager-before-v3-st.md +- Verification lane: fast +- Policy sensitivity: standard +- Blast radius: cross-cutting ### Task: docs-demo: write v3 headless execute and smart-home agent screencast script - Title: docs-demo: write v3 headless execute and smart-home agent screencast script - Mode: single-agent -- Status: backlog -- Owner: planner +- Status: done +- Owner: implementer - Brief: .fas/tasks/docs-demo-write-v3-headless-execute-and-smart-home-agent-scr.md +- Verification lane: fast +- Policy sensitivity: standard +- Blast radius: cross-cutting ### Task: playgrounds: add published-package Open in StackBlitz links after the v3 stable tag diff --git a/.fas/queue/tasks.json b/.fas/queue/tasks.json index b626cd16..84d01b3b 100644 --- a/.fas/queue/tasks.json +++ b/.fas/queue/tasks.json @@ -42,7 +42,8 @@ "task-1781724711926", "task-1781805262589", "task-1781743752184", - "task-1781919547313" + "task-1781919547313", + "task-1783461996097" ], "blocks": [ "task-1781197578529" @@ -50,7 +51,7 @@ "branchBase": null, "prDependencies": [], "createdAt": "2026-06-12T19:30:13.064Z", - "updatedAt": "2026-07-07T20:52:36.298Z", + "updatedAt": "2026-07-07T22:06:53.000Z", "deferredReason": "dependency_reopened: task-1781743752184, task-1781919547313", "invalidationReason": null }, @@ -2874,6 +2875,50 @@ "workflowId": "direct-1783460401998", "branchName": "beta", "prStatus": "draft-only" + }, + { + "id": "task-1783461996096", + "task": "docs: add Ignite Element for AI Agents one-pager before v3 stable", + "priority": "high", + "source": "manual", + "taskClassification": "self-improvement", + "selfImprovementCategory": "developer-experience", + "signalFingerprint": null, + "dependsOn": [], + "blocks": [ + "task-1783461996097" + ], + "branchBase": null, + "prDependencies": [], + "prRef": null, + "completedAt": "2026-07-07T22:23:19.144Z", + "terminalOutcome": null, + "workflowId": "direct-1783462111479", + "branchName": "fas/agent-positioning-followups", + "prStatus": "draft-only" + }, + { + "id": "task-1783461996097", + "task": "docs-demo: write v3 headless execute and smart-home agent screencast script", + "priority": "high", + "source": "manual", + "taskClassification": "self-improvement", + "selfImprovementCategory": "developer-experience", + "signalFingerprint": null, + "dependsOn": [ + "task-1783461996096" + ], + "blocks": [ + "task-1781292613064" + ], + "branchBase": null, + "prDependencies": [], + "prRef": null, + "completedAt": "2026-07-07T22:23:30.482Z", + "terminalOutcome": null, + "workflowId": "direct-1783462506281", + "branchName": "fas/agent-positioning-followups", + "prStatus": "draft-only" } ], "pullRequests": [], @@ -3005,6 +3050,14 @@ "taskId": "task-1781724738855", "epicRole": "gtm-spike" }, + { + "taskId": "task-1783461996096", + "epicRole": "agent-positioning" + }, + { + "taskId": "task-1783461996097", + "epicRole": "agent-screencast" + }, { "taskId": "task-1781919547313", "epicRole": "angular-interop" diff --git a/.fas/tasks/docs-add-ignite-element-for-ai-agents-one-pager-before-v3-st.md b/.fas/tasks/docs-add-ignite-element-for-ai-agents-one-pager-before-v3-st.md index 4a36fc8a..2999b7ba 100644 --- a/.fas/tasks/docs-add-ignite-element-for-ai-agents-one-pager-before-v3-st.md +++ b/.fas/tasks/docs-add-ignite-element-for-ai-agents-one-pager-before-v3-st.md @@ -43,9 +43,12 @@ positioning themselves. ## Affected files - docs/site/src/content/docs/overview/** or docs/site/src/content/docs/guides/** - docs/site/src/content/docs/index.mdx or nearby navigation only if a link is needed +- docs/site/astro.config.mjs for the hard-coded Starlight sidebar entry ## Scope Amendments -- None. +- Add `docs/site/astro.config.mjs` because the current docs site uses a + hard-coded Starlight sidebar; adding the one-pager to navigation requires this + config entry. ## Implementation plan - Pick the page location and sidebar order after checking the current docs IA. diff --git a/.fas/tasks/docs-demo-write-v3-headless-execute-and-smart-home-agent-scr.md b/.fas/tasks/docs-demo-write-v3-headless-execute-and-smart-home-agent-scr.md index 1541e06d..a9992c1e 100644 --- a/.fas/tasks/docs-demo-write-v3-headless-execute-and-smart-home-agent-scr.md +++ b/.fas/tasks/docs-demo-write-v3-headless-execute-and-smart-home-agent-scr.md @@ -35,6 +35,7 @@ docs: behavior contract first, headless execution, then an agent/tool loop. ## Affected files - A new markdown script artifact under docs/release/demo, docs/site content, or another repo-approved release-assets location +- docs/demo/v3-headless-smart-home-screencast.md - examples/agents/smart-home/README.md only if command wording must be corrected ## Scope Amendments diff --git a/docs/demo/v3-headless-smart-home-screencast.md b/docs/demo/v3-headless-smart-home-screencast.md new file mode 100644 index 00000000..801151a4 --- /dev/null +++ b/docs/demo/v3-headless-smart-home-screencast.md @@ -0,0 +1,237 @@ +# v3 Headless Smart-Home Agent Screencast + +## Goal + +Record a 3-5 minute release demo that shows Ignite Element as a behavior +contract for people, tests, and agents: + +- define one smart-home contract once, +- inspect the agent-readable command surface, +- execute commands headlessly in Node, +- drive the same runtime from a terminal agent and browser UI, +- optionally swap to actor-web and a local MLX/OpenAI-compatible model. + +The guaranteed recording path is the deterministic scripted model. MLX and +actor-web are optional proof points, not prerequisites for the main take. + +## Setup + +From a clean repo checkout: + +```bash +pnpm install +cd examples/agents/smart-home +pnpm install --ignore-workspace --link-workspace-packages=false +npm test +``` + +For the guaranteed key-free demo: + +```bash +npm run mock +npm run demo +``` + +For actor-web-backed dogfood: + +```bash +SMART_HOME_RUNTIME=actor-web npm run mock +SMART_HOME_RUNTIME=actor-web npm run demo +``` + +For optional local MLX/OpenAI-compatible recording: + +```bash +python -m pip install mlx-lm +python -m mlx_lm.server --model --port 8080 + +MLX_MODEL= npm run mlx -- "it's bedtime" +MLX_MODEL= npm run demo:mlx +``` + +Use `MLX_BASE_URL` or `OPENAI_COMPAT_BASE_URL` to point at a different +OpenAI-compatible endpoint. Use `OPENAI_COMPAT_API_KEY` only when the endpoint +requires one. + +## Recording Flow + +### 0:00 - Open with the contract + +Show the docs page +`/ignite-element/overview/ignite-for-ai-agents/`. + +Narration: + +> Ignite Element gives agents a behavior contract instead of asking them to +> scrape the DOM. The same component exposes a custom element for people and a +> headless runtime for tools. + +Cut to `examples/agents/smart-home/src/home.ts` around `createHome()`. + +Show that `createHome()` returns the runtime surface: + +- `getSchema()` +- `execute()` +- `getView()` +- `on()` +- `watchView()` + +Point at the command metadata for `toggleLight`, `setThermostat`, `runScene`, +`dimRooms`, and `status`. Call out that scalar, object, array, and no-argument +commands all become model tool inputs. + +### 0:45 - Show schema to tools + +Open `examples/agents/smart-home/src/agentLoop.ts`. + +Narration: + +> The agent loop never queries the DOM. `igniteTools(home, dialect)` reads the +> runtime schema, turns it into provider tool definitions, runs validated tool +> calls through `execute()`, then gives the model the result as a tool response. + +Show the loop shape: + +```text +getSchema -> tools -> model tool call -> run -> execute -> tool result +``` + +Point out that the provider dialect can be Anthropic or OpenAI-compatible, while +the Ignite runtime contract stays the same. + +### 1:30 - Run the guaranteed headless path + +Run: + +```bash +cd examples/agents/smart-home +npm run mock +``` + +Show the terminal output: + +- initial state, +- scripted prompt, +- `toggleLight`, `setThermostat`, `lockDoor`, and `runScene` tool calls, +- final projected view. + +Narration: + +> This is a real Ignite runtime in Node. The scripted model makes the recording +> deterministic, and the same path is covered by tests with no DOM and no live +> model server. + +### 2:10 - Show terminal and browser sharing one runtime + +Start the bridge: + +```bash +npm run demo +``` + +Open . + +In the terminal prompt, run: + +```text +status +light kitchen on +temp bedroom 72 +scene away +``` + +Show the browser updating after each terminal command. + +Then click a browser control: + +- turn a room light on or off, +- run the `Movie` or `Morning` scene, +- lock or unlock a door. + +Show the terminal receiving the same updated view. + +Narration: + +> The Node process owns one headless runtime. The terminal agent and the browser +> bridge both use the same command/view contract, so changes made on either side +> stay synchronized. + +### 3:20 - Optional actor-web runtime swap + +Stop the server and restart: + +```bash +SMART_HOME_RUNTIME=actor-web npm run demo +``` + +Repeat one terminal command and one browser click. + +Narration: + +> The runtime can be XState-backed or actor-web-backed. Ignite still owns the +> projection, schema, commands, and tool loop. Actor-Web owns the long-lived +> runtime and emitted domain events. + +Keep this segment short. It is a proof of boundary alignment, not a deep +actor-web walkthrough. + +### 4:00 - Optional local MLX model + +In a separate terminal, start an OpenAI-compatible MLX server: + +```bash +python -m mlx_lm.server --model --port 8080 +``` + +Run either: + +```bash +MLX_MODEL= npm run mlx -- "turn off all lights and lock every door" +``` + +or: + +```bash +MLX_MODEL= npm run demo:mlx +``` + +Narration: + +> MLX works through the OpenAI-compatible dialect. Ignite does not own model +> process lifecycle or durable local-model serving; it owns the tool contract +> and the command execution against the component runtime. + +If the local model is slow or unavailable, skip this segment and use the +deterministic mock recording. + +### 4:40 - Close + +Return to the docs page or README. + +Narration: + +> The point is not a special smart-home app. The point is the shape: one Ignite +> behavior contract, a DOM projection for humans, and a headless runtime that +> tests and agents can drive without selectors. + +## Backup Plan + +If the browser bridge or local MLX path is unstable during recording, use this +shorter path: + +1. Show `home.ts` and `agentLoop.ts`. +2. Run `npm test`. +3. Run `npm run mock`. +4. Show the README commands for `npm run demo` and `npm run demo:mlx`. + +This still proves the release-critical message: the behavior contract is +headless, deterministic, and provider-neutral. + +## Links + +- Docs one-pager: `docs/site/src/content/docs/overview/ignite-for-ai-agents.mdx` +- Agent guide: `docs/site/src/content/docs/guides/agent-runtime-v3.mdx` +- Headless runtime reference: + `docs/site/src/content/docs/api/headless-runtime.mdx` +- Smart-home example: `examples/agents/smart-home` +- Tool dialect docs: `docs/ignite-tools.md` diff --git a/docs/site/astro.config.mjs b/docs/site/astro.config.mjs index 60663ad2..31821139 100644 --- a/docs/site/astro.config.mjs +++ b/docs/site/astro.config.mjs @@ -65,6 +65,10 @@ export default defineConfig({ label: "When to choose Ignite", slug: "overview/when-to-choose-ignite", }, + { + label: "For AI agents", + slug: "overview/ignite-for-ai-agents", + }, { label: "Bundle size", slug: "overview/bundle-size" }, ], }, diff --git a/docs/site/src/content/docs/index.mdx b/docs/site/src/content/docs/index.mdx index 2fded930..9f3b5352 100644 --- a/docs/site/src/content/docs/index.mdx +++ b/docs/site/src/content/docs/index.mdx @@ -46,7 +46,7 @@ That registration is both a `` custom element and a headless runt ## Pick your path - **Build a UI** — install, enable JSX once, and ship a component. Start with [Installation](/ignite-element/getting-started/installation/) → [Your first component](/ignite-element/getting-started/first-component/), then read [The Ignite model](/ignite-element/concepts/the-ignite-model/). -- **Build for agents** — drive and inspect component behavior through the headless runtime before any DOM exists. Start with [Build for agents](/ignite-element/guides/agent-runtime-v3/) and the [Headless runtime](/ignite-element/api/headless-runtime/) reference. +- **Build for agents** — drive and inspect component behavior through the headless runtime before any DOM exists. Start with [Ignite Element for AI Agents](/ignite-element/overview/ignite-for-ai-agents/), then read [Build for agents](/ignite-element/guides/agent-runtime-v3/) and the [Headless runtime](/ignite-element/api/headless-runtime/) reference. New to the idea entirely? Read [What is Ignite Element?](/ignite-element/overview/what-is-ignite-element/) for the why and how it compares to other tools. diff --git a/docs/site/src/content/docs/overview/bundle-size.mdx b/docs/site/src/content/docs/overview/bundle-size.mdx index bd3227e8..cd2c0a70 100644 --- a/docs/site/src/content/docs/overview/bundle-size.mdx +++ b/docs/site/src/content/docs/overview/bundle-size.mdx @@ -3,7 +3,7 @@ title: Bundle size description: Tree-shaken and gzip bundle-size numbers for the current public Ignite Element entrypoints. sidebar: label: Bundle size - order: 4 + order: 5 --- These numbers measure the current public `ignite-element` ESM entrypoints after a diff --git a/docs/site/src/content/docs/overview/ignite-for-ai-agents.mdx b/docs/site/src/content/docs/overview/ignite-for-ai-agents.mdx new file mode 100644 index 00000000..7e4ada45 --- /dev/null +++ b/docs/site/src/content/docs/overview/ignite-for-ai-agents.mdx @@ -0,0 +1,121 @@ +--- +title: Ignite Element for AI Agents +description: How Ignite Element exposes behavior contracts that tools, tests, humans, and local-model agents can all drive. +sidebar: + label: For AI agents + order: 4 +--- + +Ignite Element gives agents a behavior contract instead of asking them to scrape +the DOM. The same `igniteCore(...)` value that registers a custom element also +exposes a headless runtime with commands, projected view state, emitted events, +and agent-readable metadata. + +That contract is useful because it is the same surface for humans, tests, and +tools: + +- Humans click the custom element and see the projected view. +- Tests call the runtime directly and assert snapshots, views, and events. +- Agents inspect `getSchema()`, check `canExecute()`, call `execute()`, and + observe outcomes through `on(...)` or `watchView(...)`. + +Ignite is not a separate agent framework. It is the component boundary that +turns UI behavior into explicit tools. + +## The contract + +An Ignite component exposes these runtime methods before any DOM projection +exists: + +- `getSchema()` returns the current JSON-serializable contract: commands, + command metadata, declared events, raw snapshot, and projected view. +- `execute(commandName, payload?)` runs a command and returns the post-command + snapshot plus emitted events from that transition. +- `canExecute(commandName)` evaluates dynamic command availability for gated + commands. +- `getView()` returns the projected state that renderers, tests, and agents can + use without reading DOM nodes. +- `on(eventName, handler)` subscribes to public emitted events. +- `watchView(handler)` subscribes to projected view changes over time. + +Command metadata keeps model prompts and tool manifests grounded in the +component's own contract: + +```ts +commands: ({ actor, command }) => ({ + setTemperature: command( + (temperature: number) => + actor.send({ type: 'SET_TEMPERATURE', temperature }), + { + description: 'Set the thermostat target temperature.', + input: command.number({ minimum: 58, maximum: 82 }), + }, + ), +}); +``` + +The serialized schema includes the description and input shape, while the live +runtime keeps execution and availability checks close to the state source. + +## What agents should do + +The reliable flow is: + +1. Read `getSchema()` to learn the commands, payload shapes, events, snapshot, + and view. +2. Prefer the projected `view` for user-facing reasoning; use `snapshot` when + the raw state source matters. +3. Treat `gated: true` as dynamic and call `canExecute(commandName)` immediately + before invoking that command. +4. Call `execute(commandName, payload?)` and inspect the returned `events` and + `snapshot`. +5. Keep long-lived workflows synchronized with `on(...)` for events and + `watchView(...)` for projected state. + +That keeps the model out of selector guessing and stale DOM assumptions. The +agent reasons over named commands and typed state transitions. + +## Where `igniteTools` fits + +`igniteTools(runtime, dialect)` adapts the headless runtime into provider tool +definitions and tool-call execution. The runtime still owns behavior. The +dialect only translates between provider message shapes and Ignite commands. + +The smart-home example exercises this split with: + +- an XState-backed smart-home runtime, +- an actor-web-backed runtime selected with `SMART_HOME_RUNTIME=actor-web`, +- deterministic scripted-model tests, +- Anthropic tool calls, +- OpenAI-compatible tool calls for local MLX servers, +- a terminal agent and browser UI sharing one live headless runtime. + +Run it from +[`examples/agents/smart-home`](https://github.com/0xjcf/ignite-element/tree/main/examples/agents/smart-home) +to see the contract driven without a DOM first, then shared with a browser UI. + +## Ecosystem boundaries + +Ignite owns the component contract: commands, projected view state, effects, +events, schema, and headless execution. + +Provider adapters and examples can turn that contract into model tools, including +OpenAI-compatible local-model calls for MLX. Ignite does not own durable model +serving, process management, or operator setup for MLX. Those belong outside the +component package. + +Actor-Web integration follows the same boundary. `ignite-element/actor-web` +projects an Actor-Web runtime and sends explicit requests through a +command-capable source. Ignite does not become the distributed transport, +gateway, or supervision layer. + +## Read next + +- [Build for agents](/ignite-element/guides/agent-runtime-v3/) for the + behavior-first workflow. +- [Headless runtime](/ignite-element/api/headless-runtime/) for exact method + signatures and return shapes. +- [Command metadata](/ignite-element/api/command-metadata/) for tool-readable + command descriptions and input schemas. +- [Testing DSL](/ignite-element/api/testing-dsl/) for scenario and story helpers + built on the same runtime. diff --git a/examples/agents/smart-home/README.md b/examples/agents/smart-home/README.md index 0260ca97..02f00ab4 100644 --- a/examples/agents/smart-home/README.md +++ b/examples/agents/smart-home/README.md @@ -13,6 +13,9 @@ process owns the headless runtime, a terminal agent drives it with `igniteTools` and the browser `` element observes and sends commands over a thin WebSocket bridge. +For release recording, use the +[v3 headless smart-home screencast script](../../../docs/demo/v3-headless-smart-home-screencast.md). + ## Run it ```bash