undercity 1.0.0

package/AGENTS.md

@@ -0,0 +1,26 @@
+# Undercity — AGENTS.md
+
+## The MUD Agent Model
+
+Undercity's architecture is grounded in the **Multi-User Dungeon (MUD) metaphor**:
+
+- **Rooms** have events (incl. user defined events), can contain Things.
+- **The User** moves through rooms carrying an **Inventory** of data.
+- **Things** are objects that inhabit rooms — they react to events, modify inventory, and trigger actions without user input.
+- **Events** are the lifecycle hooks of each room: `onEnter`, `onExit`, `onBack`, `onReset`, `onUnload`.
+
+This model gives Undercity a natural, coherent extension path: **any new feature can be framed as a room object, thing, or event type.**
+
+---
+
+## Why MUD?
+
+The MUD metaphor was chosen because it provides:
+
+- **A coherent vocabulary** for all stakeholders (rooms, users, inventory, things)
+- **A proven extension model** — MUDs have supported objects, things, events, and multiplayer for 40+ years
+- **Natural debugging** — you can "walk" through the flow as an user, inspect inventory at each room, and trace room events
+- **A path to AI** — LLM agents fit naturally as NPCs or guides inhabiting rooms
+- **Compatibility** — new features (auth, persistence, realtime) map to well-understood MUD concepts
+
+**The MUD metaphor is the conceptual foundation of Undercity. Preserve it in all architectural decisions.**

package/README.md

@@ -0,0 +1,58 @@
+# Undercity IDE
+
+Visual flow IDE — MUD-style logic graph builder with Bootstrap code generation.
+
+Design multi-screen applications as interconnected rooms on a map, wire up event-driven workflows with a point-and-click action editor, then generate a self-contained static Bootstrap app in one click.
+
+## Quick start
+
+```bash
+npm install
+npm run dev
+```
+
+Open `http://localhost:3000` in your browser.
+
+## Usage
+
+1. **Map** — Place rooms (screens), diamonds (logic branches), and terminals (end states) on the canvas. Connect them with edges.
+2. **Savant** — Select a node and build its action sequence: display content, read/write inventory, navigate, call APIs, render forms, and more.
+3. **Generate** — Click **Generate** (or **Preview**) to produce a self-contained Bootstrap app under `generated/<project-id>/`.
+
+## Project structure
+
+```
+src/ide/            IDE client-side JavaScript and CSS
+src/ide/css/        IDE stylesheet
+src/ide/command-line/  Command palette parser and commands
+src/lib/            Shared utilities (signal, scope, state-machine, icons)
+src/generator/      Code generation engine
+src/server/         HTTP server + API routes
+src/server/routes/  API route handlers
+actions/            Action plugins (one directory per category)
+plugins/            Generator plugins (forms, wizard, multipage)
+packages/           Local npm workspace packages (http-server, parser)
+generator/base/     Bootstrap .min files + icon SVGs used during code generation
+public/             HTML entry points (index.html, testbench.html) and static icons
+public/icons/       Custom IDE toolbar icons
+public/icons/bootstrap/  Bootstrap icon subset used by the IDE
+templates/          Starter project templates
+things/             Thing definitions (reusable room objects)
+projects/           Saved user projects (created at runtime)
+generated/          Generated app output (created at runtime)
+```
+
+`tmp/` and `generated/` are excluded from version control.
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm start` | Production server |
+| `npm run dev` | Development server with `--watch` hot reload |
+
+## Tech
+
+- Node.js (ES Modules, no bundler)
+- Bootstrap 5.3.8
+- Bootstrap Icons 1.13.1

package/actions/AGENTS.md

@@ -0,0 +1,41 @@
+# Actions — Plugin Author Guide
+
+Each action lives in its own directory:
+  actions/<category>/<actionName>/
+    action.json      — IDE metadata (label, desc, params)
+    action.js        — Runtime implementation documentation
+    action.test.js   — Unit tests
+
+The category index plugin (actions/<category>/index.js) is the browser-side
+ES module that registers the category with the IDE via App.use().
+
+## action.json schema
+
+```json
+{
+  "id":            "category.actionName",
+  "category":      "category",
+  "categoryLabel": "Human Label",
+  "icon":          "bootstrap-icon-name",
+  "color":         "var(--sol-yellow)",
+  "label":         "Action Label",
+  "desc":          "Clear description stating WHEN it runs and WHERE results go.",
+  "version":       "1.0.0",
+  "params": [
+    { "name": "fieldName", "label": "Human Label", "type": "text|code|inventory-key|select|boolean|number|textarea|room" }
+  ]
+}
+```
+
+## Creating a new category plugin
+
+1. Create `actions/<category>/index.js` exporting `<Category>Plugin`
+2. Import it in `actions/index.js` and add to `ActionsPlugin.install()`
+3. Each action that differs from the server-read action.json should be defined here
+
+## Naming rules
+
+- Category IDs: lowercase, e.g. `forms`, `user`, `nav`
+- Action IDs: `<category>.<camelCaseName>`, e.g. `form.bindField`
+- Directory names must match action camelCase: `bindField/`
+- The category/action path in the directory MUST match the id in action.json

package/actions/_shared/container.js

@@ -0,0 +1,16 @@
+/**
+ * _shared/container.js — Shared helpers for action implementations.
+ * Re-exported by action.js files so tests can import behavior directly.
+ */
+
+export function _container() {
+  return document.getElementById('pw-content') ?? document.getElementById('pw-form') ?? document.body;
+}
+
+export function _esc(s) {
+  return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+export function _escA(s) {
+  return String(s ?? '').replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}

package/actions/auth/ask-login/action.json

@@ -0,0 +1,15 @@
+{
+  "id": "auth.askLogin",
+  "category": "auth",
+  "categoryLabel": "Authentication",
+  "label": "Ask — Sign In",
+  "desc": "Render the full Sign In form (email + password) into #pw-content. High-level auth action.",
+  "version": "1.0.0",
+  "params": [
+    { "name": "submitTarget",  "label": "Submit → room",       "type": "room", "placeholder": "auth-check" },
+    { "name": "forgotTarget",  "label": "Forgot password → room", "type": "room", "placeholder": "forgot" },
+    { "name": "signupTarget",  "label": "Create account → room",  "type": "room", "placeholder": "signup" },
+    { "name": "title",         "label": "Title",                   "type": "text",    "default": "Sign In" },
+    { "name": "subtitle",      "label": "Subtitle",                "type": "text",    "default": "Welcome back. Enter your credentials." }
+  ]
+}

package/actions/auth/ask-signup/action.json

@@ -0,0 +1,14 @@
+{
+  "id": "auth.askSignup",
+  "category": "auth",
+  "categoryLabel": "Authentication",
+  "label": "Ask — Create Account",
+  "desc": "Render the full Sign Up form (first/last name, email, password) into #pw-content.",
+  "version": "1.0.0",
+  "params": [
+    { "name": "submitTarget", "label": "Submit → room",       "type": "room", "placeholder": "register-check" },
+    { "name": "loginTarget",  "label": "Already have one → room", "type": "room", "placeholder": "login" },
+    { "name": "title",        "label": "Title",    "type": "text", "default": "Create Account" },
+    { "name": "subtitle",     "label": "Subtitle", "type": "text", "default": "Join us — it only takes a moment." }
+  ]
+}

package/actions/display/clear/action.json

@@ -0,0 +1,18 @@
+{
+  "id": "display.clear",
+  "category": "display",
+  "categoryLabel": "Display",
+  "icon": "type",
+  "color": "var(--sol-cyan)",
+  "label": "Clear Content",
+  "desc": "Empty the innerHTML of a selector.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "selector",
+      "label": "Target selector",
+      "type": "text",
+      "placeholder": "#my-area"
+    }
+  ]
+}

package/actions/display/clear/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for display.clear
+ * Clear Content: Empty the innerHTML of a selector.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'display.clear — is exported from runtime',
+    run(RT) {
+      const ns = RT.Display ?? RT.display;
+      if (!ns) throw new Error('Namespace Display/display not found in runtime');
+      if (typeof ns.clear !== 'function') throw new Error('display.clear is not a function');
+    },
+  },
+
+  {
+    name: 'display.clear — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Display.clear?.("#my-area");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/display/markdown/action.json

@@ -0,0 +1,12 @@
+{
+  "id": "display.markdown",
+  "category": "display",
+  "categoryLabel": "Display",
+  "label": "Print Markdown",
+  "desc": "Render a Markdown string as HTML inside a selector.",
+  "version": "1.0.0",
+  "params": [
+    { "name": "selector", "label": "Target selector", "type": "text",     "placeholder": "#my-area" },
+    { "name": "content",  "label": "Markdown",        "type": "textarea", "placeholder": "**Bold** and _italic_" }
+  ]
+}

package/actions/display/markdown/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for display.markdown
+ * Print Markdown: Render a Markdown string as HTML inside a selector.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'display.markdown — is exported from runtime',
+    run(RT) {
+      const ns = RT.Display ?? RT.display;
+      if (!ns) throw new Error('Namespace Display/display not found in runtime');
+      if (typeof ns.markdown !== 'function') throw new Error('display.markdown is not a function');
+    },
+  },
+
+  {
+    name: 'display.markdown — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Display.markdown?.("#my-area", "**Bold** and _italic_");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/display/rawHtml/action.json

@@ -0,0 +1,24 @@
+{
+  "id": "display.rawHtml",
+  "category": "display",
+  "categoryLabel": "Display",
+  "icon": "type",
+  "color": "var(--sol-cyan)",
+  "label": "Print Raw HTML",
+  "desc": "Inject trusted HTML directly (no sanitization). Use only with controlled content.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "selector",
+      "label": "Target selector",
+      "type": "text",
+      "placeholder": "#my-area"
+    },
+    {
+      "name": "html",
+      "label": "HTML",
+      "type": "textarea",
+      "placeholder": "<b>Trusted HTML</b>"
+    }
+  ]
+}

package/actions/display/rawHtml/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for display.rawHtml
+ * Print Raw HTML: Inject trusted HTML directly (no sanitization). Use only with controlled content.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'display.rawHtml — is exported from runtime',
+    run(RT) {
+      const ns = RT.Display ?? RT.display;
+      if (!ns) throw new Error('Namespace Display/display not found in runtime');
+      if (typeof ns.rawHtml !== 'function') throw new Error('display.rawHtml is not a function');
+    },
+  },
+
+  {
+    name: 'display.rawHtml — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Display.rawHtml?.("#my-area", "<b>Trusted HTML</b>");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/display/safeHtml/action.json

@@ -0,0 +1,24 @@
+{
+  "id": "display.safeHtml",
+  "category": "display",
+  "categoryLabel": "Display",
+  "icon": "type",
+  "color": "var(--sol-cyan)",
+  "label": "Print Safe HTML",
+  "desc": "Sanitize and inject HTML — script/event attributes stripped.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "selector",
+      "label": "Target selector",
+      "type": "text",
+      "placeholder": "#my-area"
+    },
+    {
+      "name": "html",
+      "label": "HTML",
+      "type": "textarea",
+      "placeholder": "<b>Bold</b>"
+    }
+  ]
+}

package/actions/display/safeHtml/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for display.safeHtml
+ * Print Safe HTML: Sanitize and inject HTML — script/event attributes stripped.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'display.safeHtml — is exported from runtime',
+    run(RT) {
+      const ns = RT.Display ?? RT.display;
+      if (!ns) throw new Error('Namespace Display/display not found in runtime');
+      if (typeof ns.safeHtml !== 'function') throw new Error('display.safeHtml is not a function');
+    },
+  },
+
+  {
+    name: 'display.safeHtml — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Display.safeHtml?.("#my-area", "<b>Bold</b>");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/display/text/action.js

@@ -0,0 +1,9 @@
+/**
+ * display.text — set plain text in a selector.
+ * Runtime implementation (injected into generated app via registerNamespace).
+ */
+export function text(selector, text) {
+  document.querySelectorAll(selector).forEach(el => {
+    el.textContent = String(text ?? '');
+  });
+}

package/actions/display/text/action.json

@@ -0,0 +1,12 @@
+{
+  "id": "display.text",
+  "category": "display",
+  "categoryLabel": "Display",
+  "label": "Print Text",
+  "desc": "Set plain text content inside a selector. Safe — no HTML interpretation.",
+  "version": "1.0.0",
+  "params": [
+    { "name": "selector", "label": "Target selector", "type": "text",     "placeholder": "#my-label" },
+    { "name": "text",     "label": "Text",            "type": "code",     "placeholder": "\"Hello \" + inventory.firstName" }
+  ]
+}

package/actions/display/text/action.test.js

@@ -0,0 +1,40 @@
+/**
+ * action.test.js — Tests for display.text
+ */
+import { text } from './action.js';
+
+export const tests = [
+
+  {
+    name: 'display.text — exported from runtime',
+    run(RT) {
+      if (!RT.Display?.text) throw new Error('RT.Display.text not found');
+    },
+  },
+
+  {
+    name: 'display.text — sets textContent of matching element',
+    run() {
+      const el = document.createElement('p');
+      el.id = 'test-display-target';
+      document.getElementById('pw-content').appendChild(el);
+
+      text('#test-display-target', 'Hello World');
+      if (el.textContent !== 'Hello World') throw new Error(`Got: ${el.textContent}`);
+    },
+  },
+
+  {
+    name: 'display.text — safe: does not render HTML tags',
+    run() {
+      const el = document.createElement('p');
+      el.id = 'test-display-safe';
+      document.getElementById('pw-content').appendChild(el);
+
+      text('#test-display-safe', '<b>bold</b>');
+      if (el.querySelector('b')) throw new Error('Should not render HTML');
+      if (!el.textContent.includes('<b>')) throw new Error('Should show raw tag chars');
+    },
+  },
+
+];

package/actions/display/value/action.json

@@ -0,0 +1,24 @@
+{
+  "id": "display.value",
+  "category": "display",
+  "categoryLabel": "Display",
+  "icon": "type",
+  "color": "var(--sol-cyan)",
+  "label": "Show Inventory Value",
+  "desc": "Print an inventory key's value as text into a selector.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "selector",
+      "label": "Target selector",
+      "type": "text",
+      "placeholder": "#name-label"
+    },
+    {
+      "name": "key",
+      "label": "Inventory key",
+      "type": "text",
+      "placeholder": "firstName"
+    }
+  ]
+}

package/actions/display/value/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for display.value
+ * Show Inventory Value: Print an inventory key's value as text into a selector.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'display.value — is exported from runtime',
+    run(RT) {
+      const ns = RT.Display ?? RT.display;
+      if (!ns) throw new Error('Namespace Display/display not found in runtime');
+      if (typeof ns.value !== 'function') throw new Error('display.value is not a function');
+    },
+  },
+
+  {
+    name: 'display.value — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Display.value?.("#name-label", "firstName");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/dom/addClass/action.json

@@ -0,0 +1,23 @@
+{
+  "id": "dom.addClass",
+  "category": "dom",
+  "categoryLabel": "DOM",
+  "icon": "image",
+  "color": "var(--sol-green)",
+  "label": "Add Class",
+  "desc": "Add one or more CSS classes.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "selector",
+      "label": "Selector",
+      "type": "text"
+    },
+    {
+      "name": "classes",
+      "label": "Classes",
+      "type": "text",
+      "placeholder": "is-active text-info"
+    }
+  ]
+}

package/actions/dom/addClass/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for dom.addClass
+ * Add Class: Add one or more CSS classes.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'dom.addClass — is exported from runtime',
+    run(RT) {
+      const ns = RT.Dom ?? RT.dom;
+      if (!ns) throw new Error('Namespace Dom/dom not found in runtime');
+      if (typeof ns.addClass !== 'function') throw new Error('dom.addClass is not a function');
+    },
+  },
+
+  {
+    name: 'dom.addClass — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Dom.addClass?.("", "is-active text-info");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/dom/focus/action.json

@@ -0,0 +1,17 @@
+{
+  "id": "dom.focus",
+  "category": "dom",
+  "categoryLabel": "DOM",
+  "icon": "image",
+  "color": "var(--sol-green)",
+  "label": "Focus Element",
+  "desc": "Move keyboard focus to a selector.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "selector",
+      "label": "Selector",
+      "type": "text"
+    }
+  ]
+}

package/actions/dom/focus/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for dom.focus
+ * Focus Element: Move keyboard focus to a selector.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'dom.focus — is exported from runtime',
+    run(RT) {
+      const ns = RT.Dom ?? RT.dom;
+      if (!ns) throw new Error('Namespace Dom/dom not found in runtime');
+      if (typeof ns.focus !== 'function') throw new Error('dom.focus is not a function');
+    },
+  },
+
+  {
+    name: 'dom.focus — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Dom.focus?.("");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/dom/hide/action.json

@@ -0,0 +1,18 @@
+{
+  "id": "dom.hide",
+  "category": "dom",
+  "categoryLabel": "DOM",
+  "icon": "image",
+  "color": "var(--sol-green)",
+  "label": "Hide Element",
+  "desc": "Add d-none class to matching elements.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "selector",
+      "label": "Selector",
+      "type": "text",
+      "placeholder": "#my-div"
+    }
+  ]
+}