npm - undercity - Versions diffs - 1.0.1 → 1.0.2 - Mend

undercity 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (286) hide show

package/AGENTS.md +14 -0
package/library/AGENTS.md +492 -0
package/library/display/category.json +7 -0
package/library/display/clear/action.json +11 -0
package/library/display/clear/library.js +17 -0
package/library/display/index.js +23 -0
package/library/display/markdown/action.json +12 -0
package/library/display/markdown/library.js +63 -0
package/library/display/rawHtml/action.json +12 -0
package/library/display/rawHtml/library.js +17 -0
package/library/display/safeHtml/action.json +12 -0
package/library/display/safeHtml/library.js +42 -0
package/library/display/text/action.json +12 -0
package/library/display/text/library.js +17 -0
package/library/display/value/action.json +12 -0
package/library/display/value/library.js +23 -0
package/library/example-category/category.json +7 -0
package/{actions/forms/getRange → library/example-category/example-action}/action.json +2 -5
package/library/example-category/example-action/library.js +0 -0
package/library/index.js +13 -0
package/library/index.json +7 -0
package/library/input/category.json +7 -0
package/library/input/checkbox/action.json +13 -0
package/library/input/checkbox/library.js +54 -0
package/library/input/color/action.json +13 -0
package/library/input/color/library.js +63 -0
package/library/input/date/action.json +15 -0
package/library/input/date/library.js +54 -0
package/library/input/datetimeLocal/action.json +15 -0
package/library/input/datetimeLocal/library.js +54 -0
package/library/input/email/action.json +14 -0
package/library/input/email/library.js +53 -0
package/library/input/file/action.json +15 -0
package/library/input/file/library.js +53 -0
package/library/input/image/action.json +14 -0
package/library/input/image/library.js +59 -0
package/library/input/index.js +47 -0
package/library/input/longText/action.json +16 -0
package/library/input/longText/library.js +54 -0
package/library/input/month/action.json +13 -0
package/library/input/month/library.js +52 -0
package/library/input/number/action.json +17 -0
package/library/input/number/library.js +58 -0
package/library/input/password/action.json +15 -0
package/library/input/password/library.js +68 -0
package/library/input/radio/action.json +14 -0
package/library/input/radio/library.js +73 -0
package/library/input/range/action.json +16 -0
package/library/input/range/library.js +72 -0
package/library/input/tel/action.json +15 -0
package/library/input/tel/library.js +54 -0
package/library/input/text/action.json +16 -0
package/library/input/text/library.js +57 -0
package/library/input/time/action.json +15 -0
package/library/input/time/library.js +54 -0
package/library/input/url/action.json +14 -0
package/library/input/url/library.js +53 -0
package/library/input/week/action.json +13 -0
package/library/input/week/library.js +52 -0
package/library/new-action.js +298 -0
package/library/room/category.json +7 -0
package/library/room/emit/action.json +12 -0
package/library/room/emit/library.js +15 -0
package/library/room/index.js +17 -0
package/library/room/showNav/action.json +12 -0
package/library/room/showNav/library.js +35 -0
package/library/room/take/action.json +11 -0
package/library/room/take/library.js +11 -0
package/package.json +3 -2
package/projects/test-a/project.json +47 -25
package/src/generator/index.js +1 -1
package/src/generator/page.js +10 -5
package/src/generator/runtime.js +20 -22
package/src/ide/app.js +62 -4
package/src/ide/css/ide.css +21 -0
package/src/ide/savant.js +51 -10
package/src/ide/thing-library.js +14 -0
package/src/server/index.js +1 -1
package/src/server/routes/actions.js +18 -66
package/things/form/thing.json +15 -0
package/actions/AGENTS.md +0 -41
package/actions/_shared/container.js +0 -16
package/actions/auth/ask-login/action.json +0 -15
package/actions/auth/ask-signup/action.json +0 -14
package/actions/display/clear/action.json +0 -18
package/actions/display/clear/action.test.js +0 -32
package/actions/display/markdown/action.json +0 -12
package/actions/display/markdown/action.test.js +0 -32
package/actions/display/rawHtml/action.json +0 -24
package/actions/display/rawHtml/action.test.js +0 -32
package/actions/display/safeHtml/action.json +0 -24
package/actions/display/safeHtml/action.test.js +0 -32
package/actions/display/text/action.js +0 -9
package/actions/display/text/action.json +0 -12
package/actions/display/text/action.test.js +0 -40
package/actions/display/value/action.json +0 -24
package/actions/display/value/action.test.js +0 -32
package/actions/dom/addClass/action.json +0 -23
package/actions/dom/addClass/action.test.js +0 -32
package/actions/dom/focus/action.json +0 -17
package/actions/dom/focus/action.test.js +0 -32
package/actions/dom/hide/action.json +0 -18
package/actions/dom/hide/action.test.js +0 -32
package/actions/dom/removeClass/action.json +0 -22
package/actions/dom/removeClass/action.test.js +0 -32
package/actions/dom/scroll/action.json +0 -29
package/actions/dom/scroll/action.test.js +0 -32
package/actions/dom/setAttr/action.json +0 -29
package/actions/dom/setAttr/action.test.js +0 -32
package/actions/dom/setHtml/action.json +0 -22
package/actions/dom/setHtml/action.test.js +0 -32
package/actions/dom/setStyle/action.json +0 -29
package/actions/dom/setStyle/action.test.js +0 -32
package/actions/dom/setText/action.json +0 -24
package/actions/dom/setText/action.test.js +0 -32
package/actions/dom/show/action.json +0 -18
package/actions/dom/show/action.test.js +0 -32
package/actions/dom/toggle/action.json +0 -17
package/actions/dom/toggle/action.test.js +0 -32
package/actions/dom/toggleClass/action.json +0 -22
package/actions/dom/toggleClass/action.test.js +0 -32
package/actions/event/emit/action.json +0 -24
package/actions/event/emit/action.test.js +0 -32
package/actions/event/on/action.json +0 -23
package/actions/event/on/action.test.js +0 -32
package/actions/event/waitFor/action.json +0 -28
package/actions/event/waitFor/action.test.js +0 -32
package/actions/forms/bindField/action.js +0 -27
package/actions/forms/bindField/action.json +0 -24
package/actions/forms/bindField/action.test.js +0 -20
package/actions/forms/check/action.json +0 -22
package/actions/forms/check/action.test.js +0 -32
package/actions/forms/clearErrors/action.json +0 -11
package/actions/forms/clearErrors/action.test.js +0 -35
package/actions/forms/clearField/action.json +0 -17
package/actions/forms/clearField/action.test.js +0 -32
package/actions/forms/getField/action.json +0 -24
package/actions/forms/getField/action.test.js +0 -32
package/actions/forms/getRange/action.test.js +0 -32
package/actions/forms/getSelect/action.json +0 -22
package/actions/forms/getSelect/action.test.js +0 -32
package/actions/forms/index.js +0 -140
package/actions/forms/serialize/action.json +0 -24
package/actions/forms/serialize/action.test.js +0 -32
package/actions/forms/setCheck/action.json +0 -23
package/actions/forms/setCheck/action.test.js +0 -32
package/actions/forms/setError/action.json +0 -22
package/actions/forms/setError/action.test.js +0 -32
package/actions/forms/setField/action.js +0 -14
package/actions/forms/setField/action.json +0 -24
package/actions/forms/setField/action.test.js +0 -32
package/actions/forms/submit/action.json +0 -18
package/actions/forms/submit/action.test.js +0 -32
package/actions/forms/validate/action.json +0 -24
package/actions/forms/validate/action.test.js +0 -32
package/actions/http/delete/action.json +0 -22
package/actions/http/delete/action.test.js +0 -32
package/actions/http/get/action.json +0 -24
package/actions/http/get/action.test.js +0 -32
package/actions/http/post/action.json +0 -30
package/actions/http/post/action.test.js +0 -32
package/actions/http/put/action.json +0 -27
package/actions/http/put/action.test.js +0 -32
package/actions/http/upload/action.json +0 -35
package/actions/http/upload/action.test.js +0 -32
package/actions/index.js +0 -306
package/actions/index.json +0 -5
package/actions/input/askChoice/action.json +0 -29
package/actions/input/askChoice/action.test.js +0 -32
package/actions/input/askConfirm/action.json +0 -24
package/actions/input/askConfirm/action.test.js +0 -32
package/actions/input/askDate/action.json +0 -24
package/actions/input/askDate/action.test.js +0 -32
package/actions/input/askEmail/action.json +0 -24
package/actions/input/askEmail/action.test.js +0 -32
package/actions/input/askNumber/action.json +0 -35
package/actions/input/askNumber/action.test.js +0 -32
package/actions/input/askPassword/action.json +0 -24
package/actions/input/askPassword/action.test.js +0 -32
package/actions/input/askText/action.json +0 -36
package/actions/input/askText/action.test.js +0 -32
package/actions/logic/delay/action.json +0 -18
package/actions/logic/delay/action.test.js +0 -32
package/actions/logic/if/action.json +0 -28
package/actions/logic/if/action.test.js +0 -32
package/actions/logic/log/action.json +0 -18
package/actions/logic/log/action.test.js +0 -32
package/actions/logic/random/action.json +0 -36
package/actions/logic/random/action.test.js +0 -32
package/actions/logic/transform/action.json +0 -24
package/actions/logic/transform/action.test.js +0 -32
package/actions/media/askAudioUpload/action.json +0 -30
package/actions/media/askAudioUpload/action.test.js +0 -32
package/actions/media/askFileUpload/action.json +0 -36
package/actions/media/askFileUpload/action.test.js +0 -32
package/actions/media/askImageUpload/action.json +0 -37
package/actions/media/askImageUpload/action.test.js +0 -32
package/actions/media/askVideoUpload/action.js +0 -74
package/actions/media/askVideoUpload/action.json +0 -44
package/actions/media/askVideoUpload/action.test.js +0 -51
package/actions/media/captureWebcam/action.json +0 -24
package/actions/media/captureWebcam/action.test.js +0 -32
package/actions/nav/back/action.json +0 -11
package/actions/nav/back/action.test.js +0 -35
package/actions/nav/goto/action.json +0 -18
package/actions/nav/goto/action.test.js +0 -32
package/actions/nav/redirect/action.json +0 -28
package/actions/nav/redirect/action.test.js +0 -32
package/actions/nav/reload/action.json +0 -11
package/actions/nav/reload/action.test.js +0 -35
package/actions/nav/reset/action.json +0 -11
package/actions/nav/reset/action.test.js +0 -35
package/actions/render/alert/action.js +0 -12
package/actions/render/alert/action.json +0 -36
package/actions/render/alert/action.test.js +0 -32
package/actions/render/button/action.js +0 -15
package/actions/render/button/action.json +0 -44
package/actions/render/button/action.test.js +0 -37
package/actions/render/clear/action.js +0 -7
package/actions/render/clear/action.json +0 -11
package/actions/render/clear/action.test.js +0 -35
package/actions/render/divider/action.js +0 -8
package/actions/render/divider/action.json +0 -11
package/actions/render/divider/action.test.js +0 -35
package/actions/render/field/action.js +0 -17
package/actions/render/field/action.json +0 -59
package/actions/render/field/action.test.js +0 -57
package/actions/render/link/action.js +0 -20
package/actions/render/link/action.json +0 -30
package/actions/render/link/action.test.js +0 -32
package/actions/render/markdown/action.json +0 -18
package/actions/render/markdown/action.test.js +0 -32
package/actions/render/paragraph/action.js +0 -9
package/actions/render/paragraph/action.json +0 -32
package/actions/render/paragraph/action.test.js +0 -32
package/actions/render/section/action.js +0 -10
package/actions/render/section/action.json +0 -18
package/actions/render/section/action.test.js +0 -32
package/actions/render/subtitle/action.js +0 -9
package/actions/render/subtitle/action.json +0 -18
package/actions/render/subtitle/action.test.js +0 -32
package/actions/render/title/action.js +0 -9
package/actions/render/title/action.json +0 -30
package/actions/render/title/action.test.js +0 -44
package/actions/session/clear/action.json +0 -11
package/actions/session/clear/action.test.js +0 -35
package/actions/session/load/action.json +0 -22
package/actions/session/load/action.test.js +0 -32
package/actions/session/local/action.json +0 -22
package/actions/session/local/action.test.js +0 -32
package/actions/session/save/action.json +0 -22
package/actions/session/save/action.test.js +0 -32
package/actions/ui/accordion/action.json +0 -23
package/actions/ui/accordion/action.test.js +0 -32
package/actions/ui/badge/action.json +0 -22
package/actions/ui/badge/action.test.js +0 -32
package/actions/ui/collapse/action.json +0 -23
package/actions/ui/collapse/action.test.js +0 -32
package/actions/ui/hideModal/action.json +0 -17
package/actions/ui/hideModal/action.test.js +0 -32
package/actions/ui/loading/action.json +0 -18
package/actions/ui/loading/action.test.js +0 -32
package/actions/ui/modal/action.json +0 -18
package/actions/ui/modal/action.test.js +0 -32
package/actions/ui/progress/action.json +0 -24
package/actions/ui/progress/action.test.js +0 -32
package/actions/ui/toast/action.json +0 -29
package/actions/ui/toast/action.test.js +0 -32
package/actions/ui/tooltip/action.json +0 -17
package/actions/ui/tooltip/action.test.js +0 -32
package/actions/user/carry/action.json +0 -25
package/actions/user/carry/action.test.js +0 -32
package/actions/user/check/action.json +0 -24
package/actions/user/check/action.test.js +0 -32
package/actions/user/clear/action.json +0 -11
package/actions/user/clear/action.test.js +0 -35
package/actions/user/delete/action.json +0 -17
package/actions/user/delete/action.test.js +0 -32
package/actions/user/dump/action.json +0 -11
package/actions/user/dump/action.test.js +0 -35
package/actions/user/get/action.json +0 -24
package/actions/user/get/action.test.js +0 -32
package/actions/user/merge/action.json +0 -18
package/actions/user/merge/action.test.js +0 -32
package/actions/user/set/action.json +0 -24
package/actions/user/set/action.test.js +0 -32

package/AGENTS.md CHANGED Viewed

@@ -1,5 +1,19 @@
 # Undercity — AGENTS.md
+## DO NOT INSTALL NPM DEPENDENCIES
+npm packages are unsafe and should not be installed
+## PUSH ARCHITECTURE
+use Signal, combineLatest, Scope, Events, Disposable, CompositeDisposable, Repeater and similar
+See src/lib/signal.js src/lib/scope.js
+## USE WEB COMPONENTS
+Use web-components/custom-elements to create reusable and protable code
 ## The MUD Agent Model
 Undercity's architecture is grounded in the **Multi-User Dungeon (MUD) metaphor**:

package/library/AGENTS.md ADDED Viewed

@@ -0,0 +1,492 @@
+# library/ — Action Library Specification
+**Agents: read this entire file before touching anything in `library/`.**
+This is the authoritative specification for Undercity's action library.
+`./library/` replaces `./actions/`. Do not modify `./actions/`.
+---
+## Directory layout
+```
+library/
+  AGENTS.md              ← this file (do not edit)
+  new-action.js          ← scaffolding CLI — the ONLY way to create actions
+  index.js               ← single entry point  export default library
+  index.json             ← registry: which categories and actions exist
+  <category>/
+    category.json        ← category metadata
+    <actionName>/
+      action.json        ← IDE metadata: id, label, desc, params, icon, color
+      library.js         ← runtime implementation (Emitter API — see below)
+```
+Every file except `AGENTS.md` and `new-action.js` is either generated by
+`new-action.js` or maintained according to the schemas in this document.
+---
+## Categories
+Three categories are defined. Category id = directory name = UI label slug.
+| Directory  | id        | UI Label  | Icon              | Color              |
+|------------|-----------|-----------|-------------------|--------------------|
+| `input/`   | `input`   | Input     | `pencil-square`   | `var(--sol-blue)`  |
+| `room/`    | `room`    | Room      | `broadcast`       | `var(--sol-orange)`|
+| `display/` | `display` | Display   | `type`            | `var(--sol-cyan)`  |
+- **input** — 18 smart inline form inputs. Each renders directly onto the page
+  and reacts to Inventory in real time (two-way binding). Use `room.take` to
+  package them up.
+- **room** — Core room behaviours: emit events, show nav buttons, take a form.
+  Pinned to top in the UI because room wiring is foundational.
+- **display** — Read inventory values and display them on the page as text,
+  markdown, sanitised HTML, or raw HTML.
+---
+## Import map — no relative paths in `library.js`
+All `library.js` files import via bare specifiers. Never use `../../../` paths.
+| Bare specifier  | Resolved file               | What it exports                                             |
+|-----------------|-----------------------------|-------------------------------------------------------------|
+| `framework`     | `src/lib/signal.js`         | `Signal`, `Emitter`, `Disposable`, `CompositeDisposable`, `Repeater`, `on` |
+| `scope`         | `src/lib/scope.js`          | `Scope`                                                     |
+The importmap is already declared in `public/index.html` for the IDE. The
+generator (`src/generator/page.js`) must inject an equivalent importmap into
+every generated page's `<head>`, pointing to the copied files in `./js/`:
+```html
+<script type="importmap">
+{
+  "imports": {
+    "framework": "./js/signal.js",
+    "scope":     "./js/scope.js"
+  }
+}
+</script>
+```
+The generator must also copy `src/lib/signal.js` and `src/lib/scope.js` into
+the `js/` output directory alongside `runtime.js` and `af-icons.js`.
+---
+## Scaffolding: `new-action.js` is mandatory
+**Agents MUST run `new-action.js` to create every new action. Never create
+`action.json` or `library.js` by hand.** The tool ensures consistent structure,
+updates `index.json`, and keeps the category `index.js` in sync.
+```
+node library/new-action.js --category <id> --name <camelCaseName>
+```
+Examples:
+```
+node library/new-action.js --category input   --name text
+node library/new-action.js --category room    --name emit
+node library/new-action.js --category display --name value
+```
+The tool:
+1. Creates `library/<category>/<name>/` with `action.json` and `library.js`.
+2. Registers the action in `library/<category>/index.js`.
+3. Registers the category in `library/index.json` if not already present.
+4. Prints a checklist of fields to fill in.
+---
+## `index.json` schema
+Tracks which categories are active. Maintained by `new-action.js`.
+```json
+{
+  "categories": ["input", "room", "display"]
+}
+```
+---
+## `category.json` schema
+One per category directory. Created by `new-action.js` on first action in the
+category.
+```json
+{
+  "id":          "input",
+  "name":        "Input",
+  "icon":        "pencil-square",
+  "color":       "var(--sol-blue)",
+  "description": "Smart inline form inputs, each two-way bound to Inventory."
+}
+```
+Rules:
+- `id` must match the directory name exactly.
+- `name` is the human-readable UI label shown in the Savant sidebar.
+- `icon` is a Bootstrap Icons name (no `.svg` extension).
+- `color` is a CSS variable from the Solarized palette.
+---
+## `action.json` schema
+One per action directory. Describes the action to the IDE — no runtime code.
+```json
+{
+  "id":      "input.text",
+  "icon":    "input-cursor-text",
+  "color":   "var(--sol-blue)",
+  "label":   "Ask For Text",
+  "desc":    "Render a single-line text field on the page. Two-way bound to an inventory key — as the user types, inventory updates instantly.",
+  "version": "1.0.0",
+  "params": [
+    { "name": "key",         "label": "Inventory key", "type": "text",    "placeholder": "firstName" },
+    { "name": "label",       "label": "Label",         "type": "text",    "placeholder": "First Name" },
+    { "name": "placeholder", "label": "Placeholder",   "type": "text",    "placeholder": "Type here…" },
+    { "name": "required",    "label": "Required",      "type": "boolean", "default": false }
+  ]
+}
+```
+Rules:
+- `id` format: `<categoryId>.<camelCaseName>` — must match directory path exactly.
+- `desc` states WHEN the action runs and WHERE results go.
+- `params[].type` is one of: `text`, `code`, `textarea`, `json`, `boolean`,
+  `number`, `select`, `inventory-key`, `room`.
+- `params[].default` is optional; omit if there is no sensible default.
+- `params[].placeholder` is optional; include for text/code/textarea types.
+- `params[].options` is required when `type` is `select`.
+---
+## `library.js` — Emitter API (runtime implementation)
+Every action's runtime lives in `library.js`. This is the browser-side module
+loaded at page runtime. All actions share the same API contract.
+### API contract
+```js
+// library/<category>/<actionName>/library.js
+import { Emitter } from 'framework';
+/**
+ * run(params, ctx) — execute this action.
+ *
+ * @param {object} params  — resolved param values from action.json (user config)
+ * @param {object} ctx     — runtime context (see below)
+ * @returns {Emitter}      — lifecycle emitter (callers listen on this)
+ */
+export function run(params, ctx) {
+  const emitter = new Emitter();
+  // --- action logic here ---
+  // Use ctx.container, ctx.inventory, ctx.room, ctx.scope (see Context below)
+  // When done: emitter.emit('done', optionalResult)
+  // On error:  emitter.emit('error', new Error('reason'))
+  return emitter;          // return BEFORE async work completes
+}
+```
+### Standard emitted events
+| Event    | Payload             | Meaning                                      |
+|----------|---------------------|----------------------------------------------|
+| `render` | `HTMLElement`       | Action produced a DOM element to display     |
+| `done`   | `any` (optional)    | Action completed successfully                |
+| `error`  | `Error`             | Action failed; include a descriptive message |
+Callers subscribe like:
+```js
+const em = run(params, ctx);
+em.on('render', el => ctx.container.appendChild(el));
+em.on('done',   result => next());
+em.on('error',  err => showError(err.message));
+```
+### Context object (`ctx`)
+```js
+ctx.container  // HTMLElement — the room's content area; append rendered UI here
+ctx.inventory  // Signal<object> — read/write user inventory
+               //   read:  ctx.inventory.value.myKey
+               //   write: ctx.inventory.value = { ...ctx.inventory.value, myKey: v }
+ctx.room       // Emitter — room event bus
+               //   emit:  ctx.room.emit('myEvent', data)
+               //   listen: ctx.room.on('myEvent', fn)  → returns Disposable
+ctx.scope      // Scope — action-instance lifetime (from 'scope')
+               //   add subscriptions: ctx.scope.add(disposable)
+               //   disposed automatically when the room tears down
+```
+### Two-way binding pattern (used by all input actions)
+Input actions are **Web Components** so the DOM owns its own cleanup via
+`disconnectedCallback`. The component uses a `Scope` for subscriptions and
+disposes them when removed. `Signal.combineLatest` handles multi-signal reads.
+```js
+import { Emitter, Signal, on } from 'framework';
+import { Scope } from 'scope';
+const TAG = 'uc-input-text';
+if (!customElements.get(TAG)) {
+  customElements.define(TAG, class extends HTMLElement {
+    #scope = new Scope();
+    connectedCallback() {
+      const { params, ctx } = this;
+      // Build DOM
+      const label = document.createElement('label');
+      label.textContent = params.label ?? '';
+      const input = document.createElement('input');
+      input.type        = 'text';
+      input.name        = params.key;
+      input.placeholder = params.placeholder ?? '';
+      input.required    = params.required    ?? false;
+      this.append(label, input);
+      // Push: Inventory → DOM  (subscribe fires immediately with current value)
+      this.#scope.add(
+        ctx.inventory.subscribe(inv => {
+          const v = String(inv[params.key] ?? '');
+          if (input.value !== v) input.value = v;
+        })
+      );
+      // Push: DOM → Inventory
+      this.#scope.add(
+        on(input, 'input', () => {
+          ctx.inventory.value = { ...ctx.inventory.value, [params.key]: input.value };
+        })
+      );
+    }
+    disconnectedCallback() {
+      this.#scope.dispose();
+    }
+  });
+}
+export function run(params, ctx) {
+  const emitter = new Emitter();
+  const el      = Object.assign(document.createElement(TAG), { params, ctx });
+  emitter.emit('render', el);
+  emitter.emit('done');
+  return emitter;
+}
+```
+#### `combineLatest` — when an action depends on multiple signals
+Use `Signal.combineLatest` when the component needs to react to two or more
+signals simultaneously, e.g. inventory + a separate config signal:
+```js
+connectedCallback() {
+  const combined = Signal.combineLatest([ctx.inventory, ctx.config]);
+  this.#scope.add(combined);  // disposes the combiner's internal subs
+  this.#scope.add(
+    combined.subscribe(([inv, cfg]) => {
+      // update DOM from both signals at once
+    })
+  );
+}
+```
+Always `scope.add(combined)` before `scope.add(combined.subscribe(...))` so the
+combiner is torn down before its subscriber.
+### Rules for `library.js`
+- Import only from `'framework'`, `'scope'`, or browser built-ins. No relative paths.
+- No shared helpers between actions — each `library.js` is fully self-contained.
+  Three similar lines of code is better than a premature abstraction.
+- Input actions MUST be Web Components (one `customElements.define` per action,
+  guarded with `if (!customElements.get(TAG))`).
+- Web Components manage their own cleanup in `disconnectedCallback` via `Scope`.
+- Always `return emitter` before any async operations begin.
+- Always emit either `done` or `error` — never leave callers hanging.
+- Render actions must emit `render` before `done`.
+- Rely on push architecture — subscribe to signals, do not poll.
+---
+## Category `index.js` — plugin entry point
+Each category directory has an `index.js` that aggregates all actions in that
+category and exports a plugin object compatible with `App.use()`.
+`new-action.js` generates and maintains this file. Do not edit by hand.
+```js
+// library/input/index.js  (generated — maintained by new-action.js)
+import { run as textRun }      from './text/library.js';
+import textMeta                from './text/action.json' assert { type: 'json' };
+// ... one pair per action
+import categoryMeta            from './category.json' assert { type: 'json' };
+export const inputCategory = {
+  name: `library/${categoryMeta.id}`,
+  install(app) {
+    app.registerCategory(categoryMeta, {
+      [textMeta.id]:  { ...textMeta, run: textRun },
+      // ...
+    });
+  },
+};
+```
+---
+## `library/index.js` — single entry point
+**Do not touch this file.** It is the only file the application imports. To add
+a new category: run `new-action.js` — it keeps `index.json` up to date and
+`index.js` is regenerated from `index.json` automatically.
+```js
+// library/index.js
+import { inputCategory }   from './input/index.js';
+import { roomCategory }    from './room/index.js';
+import { displayCategory } from './display/index.js';
+export default {
+  name: 'undercity/library',
+  install(app) {
+    app.use(roomCategory);      // pinned first — foundational
+    app.use(inputCategory);
+    app.use(displayCategory);
+  },
+};
+```
+Application usage:
+```js
+import library from './library/index.js';
+app.use(library);
+```
+To switch to a hypothetical `library-v2`, change only this one import path in
+the application.
+---
+## Naming rules
+| Thing               | Convention                                  | Example              |
+|---------------------|---------------------------------------------|----------------------|
+| Category id         | lowercase, no spaces, no hyphens            | `input`              |
+| Category directory  | same as id                                  | `input/`             |
+| Action id           | `<categoryId>.<camelCaseName>`              | `input.text`         |
+| Action directory    | camelCase name only (no category prefix)    | `text/`              |
+| Web Component tag   | `uc-<category>-<name>` (kebab-case)         | `uc-input-text`      |
+| `library.js` export | named export `run`                          | `export function run`|
+---
+## Actions to port (reference)
+### `input/` — 18 actions (from `actions/index.js` → `InputPlugin`)
+| Directory         | action.json `id`         | Label                   |
+|-------------------|--------------------------|-------------------------|
+| `text/`           | `input.text`             | Ask For Text            |
+| `longText/`       | `input.longText`         | Ask For Long Text       |
+| `email/`          | `input.email`            | Ask For Email Address   |
+| `password/`       | `input.password`         | Ask For Password        |
+| `tel/`            | `input.tel`              | Ask For Phone Number    |
+| `url/`            | `input.url`              | Ask For Web Address     |
+| `number/`         | `input.number`           | Ask For Number          |
+| `range/`          | `input.range`            | Ask For Numeric Range   |
+| `date/`           | `input.date`             | Ask For Date            |
+| `datetimeLocal/`  | `input.datetimeLocal`    | Ask For Date & Time     |
+| `time/`           | `input.time`             | Ask For Time            |
+| `month/`          | `input.month`            | Ask For Month           |
+| `week/`           | `input.week`             | Ask For Week            |
+| `color/`          | `input.color`            | Ask For Color           |
+| `checkbox/`       | `input.checkbox`         | Ask With Checkbox       |
+| `radio/`          | `input.radio`            | Ask With Radio Buttons  |
+| `file/`           | `input.file`             | Ask For File            |
+| `image/`          | `input.image`            | Ask For Image           |
+Params for each are defined in `actions/index.js` → `INPUT_CATEGORY`. Copy
+them verbatim into `action.json`, then implement `library.js` using the
+two-way binding / Web Component pattern above.
+### `room/` — 3 actions (from `actions/index.js` → `RoomPlugin`)
+| Directory   | action.json `id`  | Label                    |
+|-------------|-------------------|--------------------------|
+| `emit/`     | `room.emit`       | Emit Room Event          |
+| `showNav/`  | `room.showNav`    | Show Navigation Buttons  |
+| `take/`     | `room.take`       | Take Form                |
+Params from `actions/index.js` → `ROOM_CATEGORY`.
+### `display/` — 6 actions (from `src/ide/action-library.js` → `display`)
+| Directory   | action.json `id`    | Label                  |
+|-------------|---------------------|------------------------|
+| `text/`     | `display.text`      | Print Text             |
+| `markdown/` | `display.markdown`  | Print Markdown         |
+| `safeHtml/` | `display.safeHtml`  | Print Safe HTML        |
+| `rawHtml/`  | `display.rawHtml`   | Print Raw HTML         |
+| `clear/`    | `display.clear`     | Clear Content          |
+| `value/`    | `display.value`     | Show Inventory Value   |
+Params from `src/ide/action-library.js` → `ACTION_LIBRARY.display`.
+---
+## Example: complete action
+`library/display/text/action.json`:
+```json
+{
+  "id":      "display.text",
+  "icon":    "body-text",
+  "color":   "var(--sol-cyan)",
+  "label":   "Print Text",
+  "desc":    "Set plain text content inside a DOM 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" }
+  ]
+}
+```
+`library/display/text/library.js`:
+```js
+import { Emitter } from 'framework';
+export function run(params, ctx) {
+  const emitter = new Emitter();
+  try {
+    const el = document.querySelector(params.selector);
+    if (!el) throw new Error(`display.text: selector not found: ${params.selector}`);
+    // params.text is already evaluated by the runtime before run() is called
+    el.textContent = params.text;
+    emitter.emit('done');
+  } catch (err) {
+    emitter.emit('error', err);
+  }
+  return emitter;
+}
+```

package/library/display/category.json ADDED Viewed

@@ -0,0 +1,7 @@
+{
+  "id":          "display",
+  "name":        "Display",
+  "icon":        "type",
+  "color":       "var(--sol-cyan)",
+  "description": "Display inventory values as text, markdown, or HTML."
+}

package/library/display/clear/action.json ADDED Viewed

@@ -0,0 +1,11 @@
+{
+  "id":      "display.clear",
+  "icon":    "eraser",
+  "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/library/display/clear/library.js ADDED Viewed

@@ -0,0 +1,17 @@
+// library/display/clear/library.js
+import { Emitter } from 'framework';
+export function run(params, ctx) {
+  const emitter = new Emitter();
+  try {
+    const el = document.querySelector(params.selector);
+    if (!el) throw new Error(`display.clear: selector not found: ${params.selector}`);
+    el.innerHTML = '';
+    emitter.emit('done');
+  } catch (err) {
+    emitter.emit('error', err);
+  }
+  return emitter;
+}

package/library/display/index.js ADDED Viewed

@@ -0,0 +1,23 @@
+// library/display/index.js — generated by new-action.js, do not edit by hand
+import { run as clearRun } from './clear/library.js';
+import { run as markdownRun } from './markdown/library.js';
+import { run as rawHtmlRun } from './rawHtml/library.js';
+import { run as safeHtmlRun } from './safeHtml/library.js';
+import { run as textRun } from './text/library.js';
+import { run as valueRun } from './value/library.js';
+const categoryMeta = {"id":"display","name":"Display","icon":"type","color":"var(--sol-cyan)","description":"Display inventory values as text, markdown, or HTML."};
+export const displayCategory = {
+  name: `library/${categoryMeta.id}`,
+  install(app) {
+    app.registerCategory(categoryMeta, {
+      "display.clear": { ...{"id":"display.clear","icon":"eraser","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"}]}, run: clearRun },
+      "display.markdown": { ...{"id":"display.markdown","icon":"markdown","color":"var(--sol-cyan)","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 content","type":"textarea","placeholder":"**Bold** and _italic_"}]}, run: markdownRun },
+      "display.rawHtml": { ...{"id":"display.rawHtml","icon":"code-slash","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>"}]}, run: rawHtmlRun },
+      "display.safeHtml": { ...{"id":"display.safeHtml","icon":"shield-check","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>"}]}, run: safeHtmlRun },
+      "display.text": { ...{"id":"display.text","icon":"body-text","color":"var(--sol-cyan)","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"}]}, run: textRun },
+      "display.value": { ...{"id":"display.value","icon":"database","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"}]}, run: valueRun },
+    });
+  },
+};

package/library/display/markdown/action.json ADDED Viewed

@@ -0,0 +1,12 @@
+{
+  "id":      "display.markdown",
+  "icon":    "markdown",
+  "color":   "var(--sol-cyan)",
+  "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 content","type": "textarea", "placeholder": "**Bold** and _italic_" }
+  ]
+}

package/library/display/markdown/library.js ADDED Viewed

@@ -0,0 +1,63 @@
+// library/display/markdown/library.js
+import { Emitter } from 'framework';
+function markdownToHtml(md) {
+  // Process line by line for headings, then handle inline elements.
+  const lines  = md.split('\n');
+  const output = [];
+  let   inPara = false;
+  const flushPara = () => {
+    if (inPara) { output.push('</p>'); inPara = false; }
+  };
+  const inline = str =>
+    str
+      // Bold: **text**
+      .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+      // Italic: _text_ (not preceded by word char to avoid mid-word matches)
+      .replace(/(?<!\w)_(.+?)_(?!\w)/g, '<em>$1</em>')
+      // Inline code: `code`
+      .replace(/`([^`]+)`/g, '<code>$1</code>')
+      // Links: [text](url)
+      .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+  for (const line of lines) {
+    // Blank line
+    if (line.trim() === '') {
+      flushPara();
+      continue;
+    }
+    // Headings
+    const h = line.match(/^(#{1,6})\s+(.*)/);
+    if (h) {
+      flushPara();
+      const level = h[1].length;
+      output.push(`<h${level}>${inline(h[2])}</h${level}>`);
+      continue;
+    }
+    // Normal text — accumulate into paragraph
+    if (!inPara) { output.push('<p>'); inPara = true; }
+    output.push(inline(line));
+  }
+  flushPara();
+  return output.join('');
+}
+export function run(params, ctx) {
+  const emitter = new Emitter();
+  try {
+    const el = document.querySelector(params.selector);
+    if (!el) throw new Error(`display.markdown: selector not found: ${params.selector}`);
+    el.innerHTML = markdownToHtml(params.content ?? '');
+    emitter.emit('done');
+  } catch (err) {
+    emitter.emit('error', err);
+  }
+  return emitter;
+}

package/library/display/rawHtml/action.json ADDED Viewed

@@ -0,0 +1,12 @@
+{
+  "id":      "display.rawHtml",
+  "icon":    "code-slash",
+  "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>" }
+  ]
+}