Automata Lab

An experimental sandbox for deterministic Moore-machine state transducers.
Infer, author, visualize, host, and simulate state-transducer models directly in the browser.

💻 Open Automata Lab   ▪  📄 Documentation

📚 Contents

• 🔎 Overview
• 🚀 Quick Start
• 📊 State Machine (State Transducer) Model
• 🧠 Partial-Observation Solver
• 📝 Authoring and File Format
• 🖥️ Built-In Server
• 📖 Documentation
• 🛠️ Development
• 📄 License

🔎 Overview

Automata Lab provides four connected workspaces for creating and investigating deterministic Moore-machine-inspired state transducers:

Workspace	Purpose
Editor	Authors the model through structured forms, lists, action assignments, and a transition table.
Chart	Displays and edits the same model as a UML-like graph.
Solver	Infers a reviewable candidate from partial observations of states, events, and actions.
Simulator	Provides a means to emulate the server and query the state transducer.

The application builds as a static React site for GitHub Pages. A dedicated browser Web Worker emulates the state-machine server, while a separate terminable worker performs inference. The result retains a clear client/server boundary without requiring installation or a remote service. The combined application and documentation are published at Automata Lab.

Application Settings offers independent colors for application buttons (Blue by default) and Console inline actions (their original theme Gray). Menus, lists, tabs, Transition Table dropdown controls, and Chart Palette tiles retain theme colors. See the Appearance guide for the palette and scope. Editor catalogs use a 1:2 Name/Description width ratio, and the compact vertical Chart Palette leaves more room for the Canvas.

Version 1.6.0 adds synchronized terminal-state editing, optional Simulator stopping after entry actions, terminal CSV/report columns, Solver replacement disclosure, and current-format examples and guides. New states and the stopping preference default off; Start or Reset captures the preference. Model files save as 1.4.0. Add/Edit dialog titles now identify their operation and entity, and printed tables keep headings on one line with a compact Terminal State column.

Version 1.5.0 simplifies Application Settings into General, Appearance, Chart, Server, Solver, Simulator, and Print. General groups File Saving and Console preferences together. Every settings control belongs to a named group box, with balanced side clearance, vertically aligned checkbox labels, and rounded corners shared across the interface. Choose the initial Solver results tab and control whether Simulator traces follow new rows in Application Settings. These preferences persist across reloads without changing model data.

The workspace and dialogs use consistent spacing, group-box titles, and gaps around splitters and scrolling content. Tables meet their vertical scrollbars directly, while pane and dialog action buttons stay outside scrolling content. Settings fields reflow at narrow widths. The same refinements apply to application-owned confirmation and editor dialogs; model behavior and file-format versions remain unchanged.

🚀 Quick Start

Hosted Web Application

Open the hosted Automata Lab application. Its integrated documentation includes the complete User and Developer Guides.

Run Locally

Install Git, Node.js, and npm, then run these commands in PowerShell (the same commands work in most shells):

git clone https://github.com/rohingosling/automata-lab.git
cd automata-lab/automata-web
npm ci
npm run documentation:ci
npm run dev

The development command verifies icons and the file schema, builds the Help documentation, and starts both local servers. Open the URL printed by Vite, normally http://127.0.0.1:5173/automata-lab/. Keep the terminal open; Ctrl+C stops both servers. The application and Help preview require free ports 5173 and 5174. See Development Setup for port overrides and production preview instructions.

Create Your First Model

1. Select New on the toolbar, or press Ctrl+N, to create an in-memory model.
2. In Editor, add at least one state, choose the initial state, then add any events and reusable actions you need.
3. On the selected state's Entry Actions and Exit Actions tabs, assign outputs in the order they should be reported.
4. Build the partial deterministic transition function in Transition Table, or create the same transitions visually in Chart.
5. Open State Machine and select Validate State Machine. Follow any diagnostics shown there and in the Console.
6. Use Chart → Automatic Layout to inspect the model, or enter partial observations in Solver to infer a reviewable candidate.
7. Select Save As whenever you want to preserve the portable JSON project. If no states or initial state have been defined yet, Automata Lab lists those requirements in a warning and can still save after confirmation; hosting and simulation still require a complete valid model.

Nothing is uploaded by merely opening or editing a model. Until you explicitly save, the authoring document remains in the browser page's volatile memory.

📊 State Machine (State Transducer) Model

Automata Lab implements an extended Moore machine. Its deliberate extension is to define two state-only output functions, one for entry-action output and one for exit-action output, in place of the standard Moore machine's single output function.

For strict Moore-machine operation, assign only entry actions and no exit actions. With only entry actions assigned and no exit actions assigned, the Automata Lab model is then mathematically equivalent to a Moore machine.

Standard Moore-Machine State-Transducer Definition

A Moore machine is defined as the six-tuple:

$$M = \left(S, s_0, \Sigma, \Lambda, T, G\right),$$

where $S$ is a finite set of states, $s_0 \in S$ is the initial state, $\Sigma$ is the input alphabet, $\Lambda$ is the output alphabet, $T : S \times \Sigma \to S$ is the transition function, and $G : S \to \Lambda$ is the state-only output function.

Automata Lab's Moore-Machine Inspired State-Transducer Definition

Automata Lab uses the corresponding seven-tuple, replacing the standard Moore machine output function $G$ with $G_{\mathrm{entry}}$ and $G_{\mathrm{exit}}$.

$$M_{\mathrm{AL}} = \left(S, s_0, \Sigma, \Lambda, T, G_{\mathrm{entry}}, G_{\mathrm{exit}}\right),$$

with a partial deterministic transition function and two state-only output-word functions:

$$T : S \times \Sigma \rightharpoonup S, \qquad G_{\mathrm{entry}} : S \to \Lambda^*, \qquad G_{\mathrm{exit}} : S \to \Lambda^*.$$

Here, $\Lambda^*$ is the set of finite words over the action alphabet, including the empty word $\varepsilon$. Consequently, output order and repeated action symbols are part of the model.

---

States

A finite, non-empty set of states. It contains one or more states because a finite-state transducer, including a Moore machine, has an initial state.

$$S = \{s_1, s_2, \ldots, s_n\}, \qquad 1 \le n < \infty.$$

---

Initial State

$$s_0 \in S.$$

---

Events

A list of zero or more events.

$$\Sigma = \{\sigma_1, \sigma_2, \ldots, \sigma_m\}, \qquad 0 \le m < \infty.$$

---

Actions

A list of zero or more reusable actions. The entry- and exit-output functions associate ordered action words with states.

$$\Lambda = \{\lambda_1, \lambda_2, \ldots, \lambda_k\}, \qquad 0 \le k < \infty.$$

---

Transition Function (Transition Table)

A partial deterministic transition function, implemented in Automata Lab as a transition table. Each state/event pair has at most one destination. An undefined pair leaves the current state unchanged and produces a warning.

$$T : S \times \Sigma \rightharpoonup S.$$

The standard Moore definition uses the total form $T : S \times \Sigma \to S$; Automata Lab deliberately permits a partial function for experimental models.

---

Output Function(s)

An output function to map states to entry actions, and an output function to map states to exit actions.

$$G_{\mathrm{entry}} : S \to \Lambda^*.$$ $$G_{\mathrm{exit}} : S \to \Lambda^*.$$

For a standard Moore output function $G : S \to \Lambda$, the equivalent Automata Lab functions are

$$G_{\mathrm{entry}}(s) = \langle G(s) \rangle, \qquad G_{\mathrm{exit}}(s) = \varepsilon.$$

---

Operation

When an event causes a transition from $s$ to $s' = T(s, \sigma)$, the runtime reports the output word

$$G_{\mathrm{exit}}(s) \mathbin{\cdot} G_{\mathrm{entry}}(s'),$$

where $\cdot$ denotes concatenation. Repeated action assignments remain meaningful and retain their order. A self-transition reports the state's exit actions and then its entry actions because the machine exits and re-enters that same state.

An unknown event or a defined event without a transition produces a warning and leaves the state unchanged. During Run, later buffered events continue.

Reset returns a session to its initial state, clears its traces, and emits nothing. The next Run or Step emits the initial entry actions once. A session whose event buffer becomes empty remains Running at its current state so another sequence can continue it.

🧠 Partial-Observation Solver

The Solver infers a compact deterministic candidate consistent with every supplied observation. It uses constrained state merging in the evidence-driven/red-blue family. Because finite partial evidence rarely identifies one unique machine, the Solver presents its result as a candidate with provenance and assumptions rather than as a uniquely correct or globally minimal answer.

Solver text uses explicit token prefixes:

• event_... identifies an observed event;
• state_... identifies an observed state;
• action_... identifies an observed action.

For easier entry and pasted notes, Event, State, and Action classifiers may also use title or uppercase spelling and _, -, or whitespace separators; compact forms such as EventOpen are accepted. Automata Lab canonicalizes the classifier to event_, state_, or action_ before inference while preserving the name suffix.

Each saved sequence declares one starting context: initial, continuation, or infer.

Events delimit transition steps. State and action tokens before the first event describe the starting state. State and action tokens between two events describe the destination reached by the preceding event. State and action tokens may be interleaved, while action order remains significant. The actions within an interval form that destination state's complete ordered entry-action list; an interval without actions describes an empty list.

Every observation is a hard constraint. Conflicting explicit states, incompatible complete action lists, or incompatible deterministic destinations produce explained diagnostics and no candidate. The Solver merges compatible evidence and invents hidden states when necessary, while reporting every weakly supported or invented structure. Unobserved state/event pairs remain undefined, and Solver-generated exit-action lists remain empty.

A successful candidate remains immutable during review. Candidate Review includes a summary, read-only Chart, state/action tables, transition provenance, trace coverage, inference report, and comparison with the current model. A separately confirmed Apply command replaces the local model as one undoable operation. Apply does not save or push the document.

📝 Authoring and File Format

Solver, Editor, and Chart operate on one in-memory authoring document. Editor provides the complete data-centric and keyboard-accessible workflow. Chart has equal semantic write authority and dispatches the same model commands. Moving a state preserves the current Chart pan and zoom after release. PNG/JPG Chart export defaults to a configurable 1,000-megapixel pre-allocation ceiling, adjustable from 1 through 1,000 under Application Settings → Chart → Image Export.

Incomplete drafts remain editable in memory. A structurally sound project can be saved with zero states and/or no initial state after an explicit warning; reopening it shows the same missing requirements in a dialog and in the Console. Malformed structure, invalid metadata, duplicates, dangling references, and other integrity errors still block loading or saving. Push, simulation, and Solver Apply become available only when complete semantic validation passes. Renames update every reference atomically. Deletions present their complete impact and remove dependent references as one undoable change.

The File → Import from CSV and Export to CSV submenus include one-record Model Metadata transfer using name,description,version,initial_state. Transition Table imports identify undeclared state and event names in separate selectable, read-only text areas for easy copying, while every import failure and warning is also recorded in the Console.

Automata Lab uses strict UTF-8 JSON with this top-level identity and structure:

{
  "file_id": "automata-lab-state-machine",
  "file_version": "1.4.0",
  "settings": {},
  "state_machine": {},
  "chart": {},
  "solver": {},
  "simulator": {}
}

Readers accept files 1.0.0 through 1.4.0; canonical Save always writes 1.4.0 with explicit terminal_state booleans. Older configured terminal relations migrate to true flags. Modern flags govern notation repair. The current terminal-state example and the legacy migration example load to the same model. States CSV exports name,description,terminal_state; an absent flag column preserves existing flags and defaults new states false.

Terminal State in Editor/Chart state dialogs synchronizes the flag and notation atomically. Application Settings → Simulator → Model Parameters → Enable Terminal States defaults off and is captured at Start Session or Reset. When enabled, terminal entry completes entry actions, preserves traces and stops before the next event. Initial terminal entry consumes zero events on first Run/Step. Run/Step then require Reset or a new session. Solver candidates default all flags false and disclose their removal before Apply; Undo restores them. Printing includes a Yes/No terminal column, and image exports retain notation regardless of execution policy. The built-in Worker uses strict protocol automata-lab-server/2.

The nested members are validated strictly. Automata Lab rejects unknown properties, duplicate JSON members, dangling references, duplicate transition keys, unsupported versions, and exceeded limits before replacing the current document. Chart settings and placement are portable document data.

Save Backup defaults off. When it is enabled, a file adapter with the required capability may replace a sibling .json.bak with the previous file content before saving. A browser that cannot create that sibling silently saves the current JSON once and records FILE_BACKUP_SKIPPED in the Console; it does not open a folder picker, download a second .bak file, or show a backup-warning dialog. Save uses its associated handle where available, and Save As uses one native save-file picker or one download fallback.

🖥️ Built-In Server

The browser-local server owns one immutable hosted document revision and any active isolated simulation sessions. The client owns the authoring document. The two communicate only through a validated, bounded, versioned gateway.

The File menu provides Connect, Disconnect, Test Server, Pull, and Push commands. Push validates and conditionally replaces the hosted head revision. Pull retrieves that revision while protecting dirty local work. Ordinary editing and Solver Apply affect only the client document.

Each simulation session pins the revision active when the session is created. A later Push does not mutate the existing session; the application marks it stale while allowing it to continue or Reset against its pinned snapshot. Closing it and creating a new session captures the current hosted revision.

The built-in transport remains local to the browser page. Its HTTP-shaped operations keep the client gateway compatible with an external HTTP transport adapter.

Operation	HTTP semantic
Handshake	Capability and protocol negotiation.
Liveness/readiness	GET /api/v1/health/live and GET /api/v1/health/ready.
Pull model	GET /api/v1/model.
Conditional Push	PUT /api/v1/model.
Start session	POST /api/v1/sessions.
Run or Step	POST /api/v1/sessions/{id}/run or /step.
Reset session	POST /api/v1/sessions/{id}/reset.
Close session	DELETE /api/v1/sessions/{id}.

📖 Documentation

The live documentation home, task-oriented User Guide, and implementation-focused Developer Guide build into the same GitHub Pages artifact as the application and require no hosted documentation service at runtime. Their public sources live in documentation/.

🛠️ Development

Prerequisites

• Node.js 24.15.0
• npm 11.12.1
• Playwright-supported operating-system libraries for Chromium, Firefox, and WebKit browser testing

The committed repository contains every asset needed to build and test the application. Access to a complete external Fluent icon collection is required only when adding or refreshing the curated Fluent subset.

Commands

The application package is in automata-web/. Run npm commands from that directory.

Command	Purpose
npm ci	Installs the exact locked dependency graph.
npm run dev	Starts the Vite development server.
npm run icons:check	Verifies the exact curated Fluent icon set and its hashes.
npm run icons:import -- --source <directory>	Imports the selected Fluent icons from an external master collection.
npm run audit:runtime	Verifies the lockfile-derived production closure and committed complete license inventory without network access.
npm run audit:runtime:write	Mechanically regenerates the runtime notice after an intentional reviewed dependency change.
npm run audit:advisories:offline	Queries only npm advisory data already present in the local cache; it is not a live advisory check.
npm run typecheck	Runs strict TypeScript checks.
npm run lint	Runs ESLint.
npm run test:unit	Runs all Vitest suites.
npm run test:model	Runs Phase 1 file, validation, command, runtime, Solver-observation, hashing, and property tests.
npm run test:solver	Runs Solver-focused Vitest suites.
npm run test:shell	Runs shell-focused Vitest suites.
npm run test:browser:install	Non-interactively installs the Chromium, Firefox, and WebKit revisions pinned by Playwright 1.62.1.
npm run test:browser	Runs Playwright browser tests.
npm run test:accessibility	Runs the dedicated accessibility browser suite.
npm run build	Builds and audits the application artifact.
npm run build:pages	Builds and verifies the combined application and documentation Pages artifact.
npm run test:artifact	Audits an existing production artifact.
npm run preview	Serves the audited production build locally.
npm run verify	Runs application, documentation, combined-artifact, and browser verification.

After npm ci on a clean host, run npm run test:browser:install before the browser suite. This invokes the package-local Playwright 1.62.1 CLI, not a global or newly resolved CLI, so its Chromium, Firefox, and WebKit revisions remain synchronized with package-lock.json. The command is non-interactive; it requires network access only when the matching browser cache is absent.

From the repository root, build.bat performs the locked dependency install, the pinned Playwright browser install, and the complete verification/build workflow while preserving the underlying exit status.

The committed package.json and package-lock.json pin every dependency version. The production build targets the /automata-lab/ GitHub Pages subpath.

The Fluent icon selection is declared in assets/images/icons/fluent-icons.json. Imported project copies live in assets/images/icons/fluent/; Vite serves them during development and emits only that curated subset into the production artifact. The external master collection is never required by CI, promotion, deployment, or application runtime.

📄 License

• The Automata Lab application is released under the MIT License.
• The curated Microsoft Fluent UI System Icons are distributed under Microsoft's Fluent UI System Icons MIT licence.