undercity 1.0.0

package/actions/media/askVideoUpload/action.json

@@ -0,0 +1,44 @@
+{
+  "id": "media.askVideoUpload",
+  "category": "media",
+  "categoryLabel": "Media & Upload",
+  "icon": "film",
+  "color": "var(--sol-magenta)",
+  "label": "Ask for Video Upload",
+  "desc": "Open file picker for a video. Optionally extract a preview thumbnail frame.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "label",
+      "label": "Prompt label",
+      "type": "text",
+      "placeholder": "Select a video"
+    },
+    {
+      "name": "accept",
+      "label": "Accept types",
+      "type": "text",
+      "placeholder": "video/*",
+      "default": "video/*"
+    },
+    {
+      "name": "thumbnailPrompt",
+      "label": "Thumbnail prompt",
+      "type": "text",
+      "placeholder": "Select a frame as thumbnail",
+      "default": "Select a frame that serves as a good preview thumbnail"
+    },
+    {
+      "name": "extractThumb",
+      "label": "Extract thumbnail",
+      "type": "boolean",
+      "default": true
+    },
+    {
+      "name": "into",
+      "label": "Store in var",
+      "type": "text",
+      "placeholder": "uploadedVideo"
+    }
+  ]
+}

package/actions/media/askVideoUpload/action.test.js

@@ -0,0 +1,51 @@
+/**
+ * action.test.js — Tests for media.askVideoUpload
+ * Tests verify that the upload UI is rendered correctly in the DOM.
+ */
+import { askVideoUpload } from './action.js';
+
+export const tests = [
+
+  {
+    name: 'media.askVideoUpload — exported from runtime',
+    run(RT) {
+      if (!RT.Media?.askVideoUpload) throw new Error('RT.Media.askVideoUpload not found');
+    },
+  },
+
+  {
+    name: 'media.askVideoUpload — renders upload card with file input',
+    run() {
+      const promise = askVideoUpload('Upload your video', 'video/*', '', false);
+
+      const ct = document.getElementById('pw-content');
+      const card = ct.querySelector('.pw-media-wrap');
+      if (!card) throw new Error('Expected .pw-media-wrap in #pw-content');
+
+      const input = card.querySelector('input[type="file"]');
+      if (!input) throw new Error('Expected file <input>');
+      if (input.accept !== 'video/*') throw new Error(`accept="${input.accept}", expected "video/*"`);
+
+      const prompt = card.querySelector('p');
+      if (!prompt?.textContent.includes('Upload your video'))
+        throw new Error(`Prompt text: "${prompt?.textContent}"`);
+
+      card.remove();
+      promise.catch(() => {});
+    },
+  },
+
+  {
+    name: 'media.askVideoUpload — renders prompt label',
+    run() {
+      const promise = askVideoUpload('Choose a video file');
+      const card = document.getElementById('pw-content').querySelector('.pw-media-wrap');
+      const p = card?.querySelector('p');
+      if (!p?.textContent.includes('Choose a video file'))
+        throw new Error(`Prompt: "${p?.textContent}"`);
+      card?.remove();
+      promise.catch(() => {});
+    },
+  },
+
+];

package/actions/media/captureWebcam/action.json

@@ -0,0 +1,24 @@
+{
+  "id": "media.captureWebcam",
+  "category": "media",
+  "categoryLabel": "Media & Upload",
+  "icon": "film",
+  "color": "var(--sol-magenta)",
+  "label": "Capture from Webcam",
+  "desc": "Ask camera permission and capture a still photo.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "label",
+      "label": "Prompt label",
+      "type": "text",
+      "placeholder": "Take a photo"
+    },
+    {
+      "name": "into",
+      "label": "Store in var",
+      "type": "text",
+      "placeholder": "photo"
+    }
+  ]
+}

package/actions/media/captureWebcam/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for media.captureWebcam
+ * Capture from Webcam: Ask camera permission and capture a still photo.
+ *
+ * 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: 'media.captureWebcam — is exported from runtime',
+    run(RT) {
+      const ns = RT.Media ?? RT.media;
+      if (!ns) throw new Error('Namespace Media/media not found in runtime');
+      if (typeof ns.captureWebcam !== 'function') throw new Error('media.captureWebcam is not a function');
+    },
+  },
+
+  {
+    name: 'media.captureWebcam — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Media.captureWebcam?.("Take a photo");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/nav/back/action.json

@@ -0,0 +1,11 @@
+{
+  "id": "nav.back",
+  "category": "navigation",
+  "categoryLabel": "Navigation",
+  "icon": "signpost",
+  "color": "var(--sol-blue)",
+  "label": "Go Back",
+  "desc": "Return to the previous room (browser history).",
+  "version": "1.0.0",
+  "params": []
+}

package/actions/nav/back/action.test.js

@@ -0,0 +1,35 @@
+/**
+ * action.test.js — Unit tests for nav.back
+ * Go Back: Return to the previous room (browser history).
+ *
+ * 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: 'nav.back — is exported from runtime',
+    run(RT) {
+      const ns = RT.Nav ?? RT.nav;
+      if (!ns) throw new Error('Namespace Nav/nav not found in runtime');
+      if (typeof ns.back !== 'function') throw new Error('nav.back is not a function');
+    },
+  },
+
+  {
+    name: 'nav.back — can be called with no arguments',
+    async run(RT, sandbox) {
+      // Smoke test: calling the action should not throw
+      // (may produce DOM changes or be a no-op depending on state)
+      try {
+        await RT.Nav.back?.();
+      } catch (e) {
+        // Some actions require specific DOM state — acceptable
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/nav/goto/action.json

@@ -0,0 +1,18 @@
+{
+  "id": "nav.goto",
+  "category": "navigation",
+  "categoryLabel": "Navigation",
+  "icon": "signpost",
+  "color": "var(--sol-blue)",
+  "label": "Go To Room",
+  "desc": "Navigate the user to another room in the flow.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "target",
+      "label": "Room",
+      "type": "room",
+      "placeholder": "room-id"
+    }
+  ]
+}

package/actions/nav/goto/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for nav.goto
+ * Go To Room: Navigate the user to another room in the flow.
+ *
+ * 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: 'nav.goto — is exported from runtime',
+    run(RT) {
+      const ns = RT.Nav ?? RT.nav;
+      if (!ns) throw new Error('Namespace Nav/nav not found in runtime');
+      if (typeof ns.goto !== 'function') throw new Error('nav.goto is not a function');
+    },
+  },
+
+  {
+    name: 'nav.goto — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Nav.goto?.("room-id");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/nav/redirect/action.json

@@ -0,0 +1,28 @@
+{
+  "id": "nav.redirect",
+  "category": "navigation",
+  "categoryLabel": "Navigation",
+  "icon": "signpost",
+  "color": "var(--sol-blue)",
+  "label": "Redirect URL",
+  "desc": "Navigate to an absolute or relative URL.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "url",
+      "label": "URL",
+      "type": "text",
+      "placeholder": "https://…"
+    },
+    {
+      "name": "target",
+      "label": "Open in",
+      "type": "select",
+      "options": [
+        "_self",
+        "_blank"
+      ],
+      "default": "_self"
+    }
+  ]
+}

package/actions/nav/redirect/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for nav.redirect
+ * Redirect URL: Navigate to an absolute or relative URL.
+ *
+ * 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: 'nav.redirect — is exported from runtime',
+    run(RT) {
+      const ns = RT.Nav ?? RT.nav;
+      if (!ns) throw new Error('Namespace Nav/nav not found in runtime');
+      if (typeof ns.redirect !== 'function') throw new Error('nav.redirect is not a function');
+    },
+  },
+
+  {
+    name: 'nav.redirect — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Nav.redirect?.("https://…", "_self");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/nav/reload/action.json

@@ -0,0 +1,11 @@
+{
+  "id": "nav.reload",
+  "category": "navigation",
+  "categoryLabel": "Navigation",
+  "icon": "signpost",
+  "color": "var(--sol-blue)",
+  "label": "Reload Page",
+  "desc": "Hard-reload the current room.",
+  "version": "1.0.0",
+  "params": []
+}

package/actions/nav/reload/action.test.js

@@ -0,0 +1,35 @@
+/**
+ * action.test.js — Unit tests for nav.reload
+ * Reload Page: Hard-reload the current room.
+ *
+ * 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: 'nav.reload — is exported from runtime',
+    run(RT) {
+      const ns = RT.Nav ?? RT.nav;
+      if (!ns) throw new Error('Namespace Nav/nav not found in runtime');
+      if (typeof ns.reload !== 'function') throw new Error('nav.reload is not a function');
+    },
+  },
+
+  {
+    name: 'nav.reload — can be called with no arguments',
+    async run(RT, sandbox) {
+      // Smoke test: calling the action should not throw
+      // (may produce DOM changes or be a no-op depending on state)
+      try {
+        await RT.Nav.reload?.();
+      } catch (e) {
+        // Some actions require specific DOM state — acceptable
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/nav/reset/action.json

@@ -0,0 +1,11 @@
+{
+  "id": "nav.reset",
+  "category": "navigation",
+  "categoryLabel": "Navigation",
+  "icon": "signpost",
+  "color": "var(--sol-blue)",
+  "label": "Reset Flow",
+  "desc": "Clear inventory and return the user to the Lobby.",
+  "version": "1.0.0",
+  "params": []
+}

package/actions/nav/reset/action.test.js

@@ -0,0 +1,35 @@
+/**
+ * action.test.js — Unit tests for nav.reset
+ * Reset Flow: Clear inventory and return the user to the Lobby.
+ *
+ * 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: 'nav.reset — is exported from runtime',
+    run(RT) {
+      const ns = RT.Nav ?? RT.nav;
+      if (!ns) throw new Error('Namespace Nav/nav not found in runtime');
+      if (typeof ns.reset !== 'function') throw new Error('nav.reset is not a function');
+    },
+  },
+
+  {
+    name: 'nav.reset — can be called with no arguments',
+    async run(RT, sandbox) {
+      // Smoke test: calling the action should not throw
+      // (may produce DOM changes or be a no-op depending on state)
+      try {
+        await RT.Nav.reset?.();
+      } catch (e) {
+        // Some actions require specific DOM state — acceptable
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/render/alert/action.js

@@ -0,0 +1,12 @@
+/** render.alert — Append a Bootstrap alert box */
+import { _container, _escA } from '../../_shared/container.js';
+
+export function alert(id = 'pw-alert', type = 'danger', text = '') {
+  const div = document.createElement('div');
+  div.id = id;
+  div.className = `alert alert-${_escA(type)} py-2${text ? '' : ' d-none'}`;
+  div.setAttribute('role', 'alert');
+  div.setAttribute('aria-live', 'polite');
+  if (text) div.textContent = String(text);
+  _container().appendChild(div);
+}

package/actions/render/alert/action.json

@@ -0,0 +1,36 @@
+{
+  "id": "render.alert",
+  "category": "render",
+  "categoryLabel": "Page Builder",
+  "icon": "layout-text-window",
+  "color": "var(--sol-violet)",
+  "label": "Alert Box",
+  "desc": "Append a hidden Bootstrap alert (show via display.text or form errors).",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "id",
+      "label": "Element ID",
+      "type": "text",
+      "placeholder": "login-alert"
+    },
+    {
+      "name": "type",
+      "label": "Type",
+      "type": "select",
+      "options": [
+        "danger",
+        "warning",
+        "info",
+        "success"
+      ],
+      "default": "danger"
+    },
+    {
+      "name": "text",
+      "label": "Initial text (leave blank to hide)",
+      "type": "text",
+      "default": ""
+    }
+  ]
+}

package/actions/render/alert/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for render.alert
+ * Alert Box: Append a hidden Bootstrap alert (show via display.text or form errors).
+ *
+ * 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: 'render.alert — is exported from runtime',
+    run(RT) {
+      const ns = RT.Render ?? RT.render;
+      if (!ns) throw new Error('Namespace Render/render not found in runtime');
+      if (typeof ns.alert !== 'function') throw new Error('render.alert is not a function');
+    },
+  },
+
+  {
+    name: 'render.alert — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Render.alert?.("login-alert", "danger", "");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/render/button/action.js

@@ -0,0 +1,15 @@
+/** render.button — Append a Bootstrap button that navigates to a target room */
+import { _container, _escA } from '../../_shared/container.js';
+
+export function button(label = '', target = '', variant = 'primary', full = true) {
+  const btn = document.createElement('button');
+  btn.type = 'button';
+  btn.className = `btn btn-${_escA(variant)} fw-semibold${(full === true || String(full) === 'true') ? ' w-100 mt-3' : ' mt-2'}`;
+  btn.textContent = String(label);
+  btn.addEventListener('click', () => {
+    const fn = 'goTo_' + String(target).replace(/[^a-zA-Z0-9]/g, '_');
+    if (typeof window[fn] === 'function') window[fn]();
+    else if (target && typeof window.Navigator !== 'undefined') window.Navigator.goto(target);
+  });
+  _container().appendChild(btn);
+}

package/actions/render/button/action.json

@@ -0,0 +1,44 @@
+{
+  "id": "render.button",
+  "category": "render",
+  "categoryLabel": "Page Builder",
+  "icon": "layout-text-window",
+  "color": "var(--sol-violet)",
+  "label": "Button",
+  "desc": "Append a button that navigates to a room (runs onExit first).",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "label",
+      "label": "Label",
+      "type": "text",
+      "placeholder": "Sign In"
+    },
+    {
+      "name": "target",
+      "label": "Room",
+      "type": "room",
+      "placeholder": "auth-check"
+    },
+    {
+      "name": "variant",
+      "label": "Style",
+      "type": "select",
+      "options": [
+        "primary",
+        "secondary",
+        "outline-secondary",
+        "outline-info",
+        "danger",
+        "success"
+      ],
+      "default": "primary"
+    },
+    {
+      "name": "full",
+      "label": "Full width",
+      "type": "boolean",
+      "default": true
+    }
+  ]
+}

package/actions/render/button/action.test.js

@@ -0,0 +1,37 @@
+/**
+ * action.test.js — Tests for render.button
+ */
+import { button } from './action.js';
+
+export const tests = [
+
+  {
+    name: 'render.button — exported from runtime',
+    run(RT) {
+      if (!RT.Render?.button) throw new Error('RT.Render.button not found');
+    },
+  },
+
+  {
+    name: 'render.button — appends <button> with label and primary class',
+    run() {
+      button('Sign In', 'auth-check', 'primary', true);
+      const btn = document.getElementById('pw-content').querySelector('button');
+      if (!btn) throw new Error('No button');
+      if (!btn.textContent.includes('Sign In')) throw new Error(`Label: ${btn.textContent}`);
+      if (!btn.classList.contains('btn-primary')) throw new Error('Missing btn-primary');
+      if (!btn.classList.contains('w-100')) throw new Error('Missing w-100 (full=true)');
+    },
+  },
+
+  {
+    name: 'render.button — full=false omits w-100',
+    run() {
+      button('Back', 'lobby', 'outline-secondary', false);
+      const btn = document.getElementById('pw-content').querySelector('button');
+      if (!btn) throw new Error('No button');
+      if (btn.classList.contains('w-100')) throw new Error('Should not have w-100 when full=false');
+    },
+  },
+
+];

package/actions/render/clear/action.js

@@ -0,0 +1,7 @@
+/** render.clear — Clear #pw-content */
+import { _container } from '../../_shared/container.js';
+
+export function clear() {
+  const c = _container();
+  if (c) c.innerHTML = '';
+}

package/actions/render/clear/action.json

@@ -0,0 +1,11 @@
+{
+  "id": "render.clear",
+  "category": "render",
+  "categoryLabel": "Page Builder",
+  "icon": "layout-text-window",
+  "color": "var(--sol-violet)",
+  "label": "Clear Page",
+  "desc": "Empty #pw-content. Put this first in onEnter to rebuild on each visit.",
+  "version": "1.0.0",
+  "params": []
+}

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

@@ -0,0 +1,35 @@
+/**
+ * action.test.js — Unit tests for render.clear
+ * Clear Page: Empty #pw-content. Put this first in onEnter to rebuild on each visit.
+ *
+ * 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: 'render.clear — is exported from runtime',
+    run(RT) {
+      const ns = RT.Render ?? RT.render;
+      if (!ns) throw new Error('Namespace Render/render not found in runtime');
+      if (typeof ns.clear !== 'function') throw new Error('render.clear is not a function');
+    },
+  },
+
+  {
+    name: 'render.clear — can be called with no arguments',
+    async run(RT, sandbox) {
+      // Smoke test: calling the action should not throw
+      // (may produce DOM changes or be a no-op depending on state)
+      try {
+        await RT.Render.clear?.();
+      } catch (e) {
+        // Some actions require specific DOM state — acceptable
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/render/divider/action.js

@@ -0,0 +1,8 @@
+/** render.divider — Append a horizontal divider */
+import { _container } from '../../_shared/container.js';
+
+export function divider() {
+  const hr = document.createElement('hr');
+  hr.className = 'my-3 border-secondary';
+  _container().appendChild(hr);
+}