pico-engine 1.9.4 → 1.9.5

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 (84) hide show
  1. package/README.md +2 -0
  2. package/demos/bootstrap/README.md +12 -0
  3. package/demos/bootstrap/com.example.visitors.bootstrap.krl +97 -0
  4. package/demos/bootstrap/com.example.visitors.format.krl +25 -0
  5. package/demos/bootstrap/com.example.visitors.krl +228 -0
  6. package/demos/bootstrap/try-it.md +5 -0
  7. package/demos/child_tasks/README.md +12 -0
  8. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +85 -0
  9. package/demos/child_tasks/com.example.task_runner.krl +139 -0
  10. package/demos/child_tasks/com.example.task_worker.krl +45 -0
  11. package/demos/child_tasks/try-it.md +5 -0
  12. package/demos/collection/README.md +13 -0
  13. package/demos/collection/com.example.collection.bootstrap.krl +148 -0
  14. package/demos/collection/com.example.collection.krl +95 -0
  15. package/demos/collection/com.example.collection.report.krl +93 -0
  16. package/demos/collection/com.example.collection.room.krl +101 -0
  17. package/demos/collection/try-it.md +6 -0
  18. package/demos/echo/README.md +11 -0
  19. package/demos/echo/com.example.echo.bootstrap.krl +81 -0
  20. package/demos/echo/com.example.echo.krl +73 -0
  21. package/demos/echo/try-it.md +5 -0
  22. package/demos/guard_rules/README.md +12 -0
  23. package/demos/guard_rules/com.example.archive.bootstrap.krl +95 -0
  24. package/demos/guard_rules/com.example.archive.krl +213 -0
  25. package/demos/guard_rules/com.example.archive_store.krl +36 -0
  26. package/demos/guard_rules/try-it.md +5 -0
  27. package/demos/kblog/README.md +14 -0
  28. package/demos/kblog/com.example.kblog.bootstrap.krl +132 -0
  29. package/demos/kblog/com.example.kblog.config.krl +50 -0
  30. package/demos/kblog/com.example.kblog.data.krl +75 -0
  31. package/demos/kblog/com.example.kblog.krl +184 -0
  32. package/demos/kblog/com.example.kblog.posting.krl +109 -0
  33. package/demos/kblog/try-it.md +6 -0
  34. package/demos/layered_rulesets/README.md +13 -0
  35. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +84 -0
  36. package/demos/layered_rulesets/com.example.invitations.krl +164 -0
  37. package/demos/layered_rulesets/com.example.invitations.short_links.krl +45 -0
  38. package/demos/layered_rulesets/com.example.invitations.welcome.krl +39 -0
  39. package/demos/layered_rulesets/try-it.md +5 -0
  40. package/demos/moving_picos/README.md +15 -0
  41. package/demos/moving_picos/io.picolabs.club_gear_demo.krl +650 -0
  42. package/demos/moving_picos/io.picolabs.ride_coordinator_demo.krl +331 -0
  43. package/demos/score_tracker/README.md +11 -0
  44. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +104 -0
  45. package/demos/score_tracker/com.example.score_tracker.krl +162 -0
  46. package/demos/score_tracker/try-it.md +5 -0
  47. package/demos/secrets/README.md +12 -0
  48. package/demos/secrets/com.example.hook_service.krl +120 -0
  49. package/demos/secrets/com.example.notifier.bootstrap.krl +127 -0
  50. package/demos/secrets/com.example.notifier.krl +138 -0
  51. package/demos/secrets/try-it.md +5 -0
  52. package/demos/try-it-order.json +1 -0
  53. package/demos/two_picos/README.md +12 -0
  54. package/demos/two_picos/com.example.two_picos.answerer.krl +125 -0
  55. package/demos/two_picos/com.example.two_picos.asker.krl +124 -0
  56. package/demos/two_picos/com.example.two_picos.bootstrap.krl +131 -0
  57. package/demos/two_picos/try-it.md +5 -0
  58. package/demos/xmlui/README.md +17 -0
  59. package/demos/xmlui/com.example.contacts.krl +132 -0
  60. package/demos/xmlui/com.example.fav_color.krl +39 -0
  61. package/demos/xmlui/com.example.guestbook.krl +61 -0
  62. package/demos/xmlui/com.example.hello.krl +19 -0
  63. package/demos/xmlui/com.example.temperature_sensors_view.krl +105 -0
  64. package/demos/xmlui/com.example.thermostat.bootstrap.krl +92 -0
  65. package/demos/xmlui/com.example.thermostat.krl +124 -0
  66. package/demos/xmlui/temperature_sensors.krl +56 -0
  67. package/demos/xmlui/try-it.md +5 -0
  68. package/dist/bundledKrl.js +97 -12
  69. package/dist/cli.js +2 -0
  70. package/dist/engineConfig.js +19 -0
  71. package/dist/index.js +1 -0
  72. package/dist/server.js +14 -0
  73. package/krl/io.picolabs.xmlui.krl +3 -2
  74. package/mcp/docs/CLAUDE.md +3 -2
  75. package/mcp/docs/pico-engine.md +3 -0
  76. package/package.json +6 -3
  77. package/public/.DS_Store +0 -0
  78. package/public/pico-engine-ui.css +1 -1
  79. package/public/pico-engine-ui.js +23 -22
  80. package/src/bundledKrl.ts +118 -12
  81. package/src/cli.ts +2 -0
  82. package/src/engineConfig.ts +28 -0
  83. package/src/index.ts +8 -0
  84. package/src/server.ts +15 -0
@@ -0,0 +1,124 @@
1
+ ruleset com.example.thermostat {
2
+ meta {
3
+ name "Thermostat"
4
+ use module io.picolabs.xmlui alias ui
5
+ shares readings, threshold, dashboard, settings, readingHistory
6
+ }
7
+ global {
8
+ /**
9
+ * Recent readings, newest first (updates after thermostat new_reading).
10
+ * @returns Array
11
+ * @example "history" {}
12
+ */
13
+ readings = function() {
14
+ ent:readings.defaultsTo([]).reverse()
15
+ }
16
+
17
+ /**
18
+ * Alert threshold in degrees F
19
+ * @returns Number
20
+ * @example "default" {}
21
+ */
22
+ threshold = function() {
23
+ ent:threshold.defaultsTo(80)
24
+ }
25
+
26
+ /**
27
+ * Readings as a table. Props: rows (Array of { time, temperature }).
28
+ * @component
29
+ */
30
+ readingHistory = function() {
31
+ <<
32
+ <Component name="ReadingHistory">
33
+ <Table data="{$props.rows}">
34
+ <Column bindTo="time" header="Time" />
35
+ <Column bindTo="temperature" header="Temperature (F)" />
36
+ </Table>
37
+ </Component>
38
+ >>
39
+ }
40
+
41
+ /**
42
+ * Current temperature and history. Display picks the theme, using the
43
+ * shared PicoSettings, PicoThemeField, and PicoTheme components.
44
+ * @view "Dashboard"
45
+ */
46
+ dashboard = function() {
47
+ <<
48
+ <Component name="Dashboard">
49
+ #{ui:query("readings", "readings", {"rid": meta:rid})}
50
+ #{ui:query("threshold", "threshold", {"rid": meta:rid})}
51
+ <PicoSettings id="display" title="Display">
52
+ <PicoThemeField />
53
+ </PicoSettings>
54
+ <PicoTheme>
55
+ <HStack horizontalAlignment="end">
56
+ <Button label="Display" onClick="display.open()" />
57
+ </HStack>
58
+ <Card title="Now: {readings.value[0].temperature} F"
59
+ subtitle="Alert above {threshold.value} F" />
60
+ <ReadingHistory rows="{readings}" />
61
+ </PicoTheme>
62
+ </Component>
63
+ >>
64
+ }
65
+
66
+ /**
67
+ * Change the alert threshold
68
+ * @view "Settings"
69
+ */
70
+ settings = function() {
71
+ <<
72
+ <Component name="Settings">
73
+ #{ui:query("threshold", "threshold", {"rid": meta:rid})}
74
+ #{ui:event("setThreshold", "thermostat", "threshold_set",
75
+ {"rid": meta:rid, "refresh": ["threshold"], "confirm": "Change the alert threshold?"})}
76
+ <Form data="{{ threshold: threshold.value }}"
77
+ onSubmit="(toSave) => setThreshold.execute(toSave)">
78
+ <FormItem bindTo="threshold" label="Alert above (F)" type="integer" />
79
+ </Form>
80
+ </Component>
81
+ >>
82
+ }
83
+
84
+ viewer_tags = ["thermostat", "viewer"]
85
+ admin_tags = ["thermostat", "admin"]
86
+ }
87
+
88
+ /**
89
+ * Record a temperature reading (shown on the Dashboard view).
90
+ * @attr temperature Number Degrees Fahrenheit
91
+ * @example "room temperature" { "temperature": "72" }
92
+ * @example "warm alert" { "temperature": "85" }
93
+ */
94
+ rule record_reading {
95
+ select when thermostat new_reading
96
+ temperature re#(.+)# setting(temperature)
97
+ fired {
98
+ ent:readings := ent:readings.defaultsTo([])
99
+ .append({"temperature": temperature.as("Number"), "time": time:now()})
100
+ }
101
+ }
102
+
103
+ /**
104
+ * Set the alert threshold (same as the Settings view form).
105
+ * @attr threshold Number Degrees Fahrenheit
106
+ * @example "alert at 80 F" { "threshold": "80" }
107
+ * @example "alert at 75 F" { "threshold": "75" }
108
+ */
109
+ rule set_threshold {
110
+ select when thermostat threshold_set
111
+ threshold re#^(\d+)$# setting(threshold)
112
+ fired {
113
+ ent:threshold := threshold.as("Number")
114
+ }
115
+ }
116
+
117
+ rule create_app_channels {
118
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
119
+ every {
120
+ ui:create_app_channel(viewer_tags, [], ["readings", "threshold", "dashboard"], meta:rid)
121
+ ui:create_app_channel(admin_tags, ["thermostat"], null, meta:rid)
122
+ }
123
+ }
124
+ }
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Demo data ruleset: `latestReadings` returns a fixed array (no `picoQuery`).
3
+ * Install on the **data** pico. The view demo (`com.example.temperature_sensors_view`)
4
+ * queries this ruleset over a relationship/subscription Tx (`wrangler:picoQuery`).
5
+ *
6
+ * Shape per row: `name`, `lastTemperature`, `readingAt`, `timestamp`.
7
+ */
8
+ ruleset com.example.temperature_sensors {
9
+ meta {
10
+ name "Temperature sensors (static demo)"
11
+ description "Static sample readings for XMLUI demos"
12
+ provides latestReadings
13
+ shares latestReadings
14
+ }
15
+
16
+ global {
17
+ /**
18
+ * Fixed sample readings (replace with real data or `ent:` when you are ready).
19
+ * @returns Array
20
+ */
21
+ latestReadings = function() {
22
+ [
23
+ {
24
+ "name": "Sensors:Beehive",
25
+ "lastTemperature": 51.47,
26
+ "readingAt": "2026-11-06 19:11:14 Coordinated Universal Time",
27
+ "timestamp": 1793992274126
28
+ },
29
+ {
30
+ "name": "Sensors:Cabin Crawl Space",
31
+ "lastTemperature": 55.4,
32
+ "readingAt": "2026-11-06 19:01:48 Coordinated Universal Time",
33
+ "timestamp": 1793991708383
34
+ },
35
+ {
36
+ "name": "Sensors:Cabin North Side",
37
+ "lastTemperature": 38.46,
38
+ "readingAt": "2026-11-06 18:59:45 Coordinated Universal Time",
39
+ "timestamp": 1793991585382
40
+ },
41
+ {
42
+ "name": "Sensors:Pump House",
43
+ "lastTemperature": 51.15,
44
+ "readingAt": "2026-11-06 19:01:24 Coordinated Universal Time",
45
+ "timestamp": 1793991684238
46
+ },
47
+ {
48
+ "name": "Sensors:Triple Temp",
49
+ "lastTemperature": 51.08,
50
+ "readingAt": "2026-11-06 19:11:54 Coordinated Universal Time",
51
+ "timestamp": 1793992314892
52
+ }
53
+ ]
54
+ }
55
+ }
56
+ }
@@ -0,0 +1,5 @@
1
+ - Open both dashboard links. On the viewer channel the navigation has only Dashboard. On the admin channel it also has Settings.
2
+ - On **Settings**, change the alert threshold, then go back to the Dashboard.
3
+ - Click **Display** on the Dashboard. The theme picker is built from the shared `PicoSettings` and `PicoThemeField` components. The readings table is the ruleset's own `ReadingHistory` component.
4
+ - Open the child pico's **Channels** tab and compare the query policies of `thermostat, viewer` and `thermostat, admin`. That policy is the whole difference between the two views.
5
+ - On the **Testing** tab, raise `thermostat` `new_reading` with a `temperature`, and reload the dashboard.
@@ -7,7 +7,9 @@ exports.engineKrlHttpPath = engineKrlHttpPath;
7
7
  exports.engineKrlFileUrl = engineKrlFileUrl;
8
8
  exports.listEngineKrlSources = listEngineKrlSources;
9
9
  exports.engineKrlRelativeFromUrl = engineKrlRelativeFromUrl;
10
+ exports.demosDir = demosDir;
10
11
  exports.resolveEngineKrlFile = resolveEngineKrlFile;
12
+ exports.listTryItDemos = listTryItDemos;
11
13
  exports.resolveBundledKrlUrl = resolveBundledKrlUrl;
12
14
  const fs = require("fs");
13
15
  const path = require("path");
@@ -126,27 +128,110 @@ function engineKrlRelativeFromUrl(url) {
126
128
  }
127
129
  if (parsed.protocol === "http:" || parsed.protocol === "https:") {
128
130
  const match = parsed.pathname.match(/^\/krl\/(.+\.krl)$/);
129
- if (match) {
130
- const relativePath = match[1].split("/").join(path.sep);
131
- const candidate = path.join(bundledKrlDir(), relativePath);
132
- if (fs.existsSync(candidate)) {
133
- return match[1];
134
- }
131
+ if (match && resolveEngineKrlFile(match[1])) {
132
+ return match[1];
135
133
  }
136
134
  }
137
135
  return null;
138
136
  }
139
- function resolveEngineKrlFile(relativePath) {
140
- const normalized = relativePath.split("/").join(path.sep);
141
- const candidate = path.resolve(bundledKrlDir(), normalized);
142
- const root = bundledKrlDir();
137
+ /**
138
+ * The demos/ directory: PICO_ENGINE_DEMOS_DIR when set (a copy someone edits
139
+ * and keeps across upgrades), else inside the package when installed from npm
140
+ * (copied at pack time), else the repository root in a checkout.
141
+ */
142
+ function demosDir() {
143
+ const override = process.env.PICO_ENGINE_DEMOS_DIR;
144
+ const candidates = [
145
+ ...(override && override.trim() ? [path.resolve(override.trim())] : []),
146
+ path.resolve(__dirname, "..", "demos"),
147
+ path.resolve(__dirname, "..", "..", "..", "demos"),
148
+ ];
149
+ for (const dir of candidates) {
150
+ if (fs.existsSync(dir) && fs.statSync(dir).isDirectory())
151
+ return dir;
152
+ }
153
+ return null;
154
+ }
155
+ function fileWithin(root, relativePath) {
156
+ const candidate = path.resolve(root, relativePath.split("/").join(path.sep));
143
157
  if (candidate.startsWith(root + path.sep) &&
144
- fs.existsSync(candidate) &&
145
- candidate.endsWith(".krl")) {
158
+ candidate.endsWith(".krl") &&
159
+ fs.existsSync(candidate)) {
146
160
  return candidate;
147
161
  }
148
162
  return null;
149
163
  }
164
+ /** `relativePath` is under krl/, or under demos/ when it starts with `demos/`. */
165
+ function resolveEngineKrlFile(relativePath) {
166
+ if (relativePath.startsWith("demos/")) {
167
+ const root = demosDir();
168
+ return root ? fileWithin(root, relativePath.slice("demos/".length)) : null;
169
+ }
170
+ return fileWithin(bundledKrlDir(), relativePath);
171
+ }
172
+ function readNotes(root, folder) {
173
+ try {
174
+ return fs.readFileSync(path.join(root, folder, "try-it.md"), "utf8");
175
+ }
176
+ catch (_a) {
177
+ return undefined;
178
+ }
179
+ }
180
+ /** Folder names from demos/try-it-order.json (a JSON array), or none if it is missing or invalid. */
181
+ function tryItOrder(root) {
182
+ try {
183
+ const order = JSON.parse(fs.readFileSync(path.join(root, "try-it-order.json"), "utf8"));
184
+ return Array.isArray(order) ? order.filter((f) => typeof f === "string") : [];
185
+ }
186
+ catch (_a) {
187
+ return [];
188
+ }
189
+ }
190
+ /**
191
+ * Every demos/<folder>/<rid>.bootstrap.krl, for the developer UI's "Try It!" tab.
192
+ * Folders named in demos/try-it-order.json come first, in that order; the rest follow by path.
193
+ */
194
+ function listTryItDemos(baseUrl) {
195
+ const root = demosDir();
196
+ if (!root)
197
+ return [];
198
+ const files = [];
199
+ for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
200
+ if (!entry.isDirectory() || entry.name.startsWith("."))
201
+ continue;
202
+ walkKrlFiles(path.join(root, entry.name), root, files);
203
+ }
204
+ const base = baseUrl.replace(/\/$/, "");
205
+ const fileInfo = (rel) => ({
206
+ rid: readKrlMeta(path.join(root, rel)).rid,
207
+ file: path.basename(rel),
208
+ url: `${base}/krl/demos/${rel}`,
209
+ path: path.join(root, rel),
210
+ });
211
+ const order = tryItOrder(root);
212
+ const rank = (rel) => {
213
+ const i = order.indexOf(rel.split("/")[0]);
214
+ return i < 0 ? order.length : i;
215
+ };
216
+ return files
217
+ .filter((rel) => rel.endsWith(".bootstrap.krl"))
218
+ .sort((a, b) => rank(a) - rank(b) || (a < b ? -1 : a > b ? 1 : 0))
219
+ .map((rel) => {
220
+ const meta = readKrlMeta(path.join(root, rel));
221
+ const folder = rel.split("/")[0];
222
+ return {
223
+ rid: meta.rid,
224
+ name: meta.name,
225
+ description: meta.description,
226
+ folder,
227
+ url: `${base}/krl/demos/${rel}`,
228
+ path: path.join(root, rel),
229
+ docs: `https://docs.picolabs.io/#/cookbook/${folder}/`,
230
+ notes: readNotes(root, folder),
231
+ files: files.filter((f) => f.split("/")[0] === folder).sort().map(fileInfo),
232
+ };
233
+ });
234
+ }
150
235
  function resolveBundledKrlUrl(url) {
151
236
  const relativePath = engineKrlRelativeFromUrl(url);
152
237
  if (!relativePath) {
package/dist/cli.js CHANGED
@@ -75,6 +75,8 @@ Environment (optional; Docker/CI when not set in config file):
75
75
  PICO_ENGINE_LOG_FILE - Log path, or stdout/- / 0 for console-only
76
76
  PICO_ENGINE_LOG_MIRROR - "true"/"1" or "false"/"0" (mirror JSON lines to \$PICO_ENGINE_HOME/pico-engine.log when stdout-only; default on)
77
77
  PICO_ENGINE_LOG_RING - how many recent transactions per pico the Logging tab keeps in memory (default 200; cleared on restart)
78
+ PICO_ENGINE_SHOW_TRYIT_MENU - off, root_only (default), or all: where the Developer UI shows the Try It! tab (config: show_tryit_menu)
79
+ PICO_ENGINE_DEMOS_DIR - directory to serve as demos/ (/krl/demos/) instead of the shipped copy
78
80
  `);
79
81
  process.exit(0);
80
82
  }
@@ -14,6 +14,15 @@ const os = require("os");
14
14
  const path = require("path");
15
15
  const policyConfigFromJson_1 = require("./policyConfigFromJson");
16
16
  const homeDir = require("home-dir");
17
+ const SHOW_TRY_IT_MENU_VALUES = ["off", "root_only", "all"];
18
+ function parseShowTryItMenu(val, source) {
19
+ if (val === undefined)
20
+ return undefined;
21
+ if (typeof val === "string" && SHOW_TRY_IT_MENU_VALUES.includes(val)) {
22
+ return val;
23
+ }
24
+ throw new Error(`${source} must be one of ${SHOW_TRY_IT_MENU_VALUES.join(", ")} (got ${JSON.stringify(val)})`);
25
+ }
17
26
  let runtimeSettings = null;
18
27
  function installEngineRuntimeSettings(settings) {
19
28
  runtimeSettings = settings;
@@ -34,6 +43,7 @@ function defaultEngineSettings() {
34
43
  wildcardSkyRequireBearer: false,
35
44
  logToStdout: false,
36
45
  logMirror: true,
46
+ showTryItMenu: "root_only",
37
47
  };
38
48
  }
39
49
  function defaultEngineConfigFilePath() {
@@ -146,6 +156,9 @@ function parseConfigFile(raw) {
146
156
  out.logFile = path.resolve(expandHome(o.logFile));
147
157
  }
148
158
  }
159
+ const showTryItMenu = parseShowTryItMenu(o.show_tryit_menu, "show_tryit_menu");
160
+ if (showTryItMenu)
161
+ out.showTryItMenu = showTryItMenu;
149
162
  const rootCeiling = (0, policyConfigFromJson_1.parsePolicyCeilingFromJson)(o.defaultRootPolicyCeiling, "defaultRootPolicyCeiling");
150
163
  if (rootCeiling) {
151
164
  out.defaultRootPolicyCeiling = rootCeiling;
@@ -227,6 +240,9 @@ function settingsFromEnv() {
227
240
  if (logMirror !== undefined) {
228
241
  out.logMirror = logMirror;
229
242
  }
243
+ const showTryItMenu = parseShowTryItMenu(process.env.PICO_ENGINE_SHOW_TRYIT_MENU || undefined, "PICO_ENGINE_SHOW_TRYIT_MENU");
244
+ if (showTryItMenu)
245
+ out.showTryItMenu = showTryItMenu;
230
246
  return out;
231
247
  }
232
248
  function mergeSettings(base, ...layers) {
@@ -277,6 +293,9 @@ function resolveEngineSettings(programmatic = {}) {
277
293
  if (programmatic.logMirror !== undefined) {
278
294
  fromProgrammatic.logMirror = programmatic.logMirror;
279
295
  }
296
+ if (programmatic.showTryItMenu !== undefined) {
297
+ fromProgrammatic.showTryItMenu = programmatic.showTryItMenu;
298
+ }
280
299
  if (programmatic.defaultRootPolicyCeiling !== undefined) {
281
300
  fromProgrammatic.defaultRootPolicyCeiling =
282
301
  programmatic.defaultRootPolicyCeiling;
package/dist/index.js CHANGED
@@ -45,6 +45,7 @@ async function startEngine(configuration = {}) {
45
45
  rpName: configuration.rpName,
46
46
  origin: configuration.origin,
47
47
  allowSelfSignup: configuration.allowSelfSignup,
48
+ showTryItMenu: configuration.showTryItMenu,
48
49
  defaultRootPolicyCeiling: configuration.defaultRootPolicyCeiling,
49
50
  globalEventDeny: configuration.globalEventDeny,
50
51
  globalQueryDeny: configuration.globalQueryDeny,
package/dist/server.js CHANGED
@@ -302,6 +302,19 @@ function server(core, uiECI, auth, oauth, identity) {
302
302
  next(err);
303
303
  }
304
304
  });
305
+ app.get("/api/try-it", function (req, res, next) {
306
+ try {
307
+ let baseUrl = core.base_url;
308
+ if (!baseUrl) {
309
+ baseUrl = `${req.protocol}://${req.get("host") || "localhost"}`;
310
+ }
311
+ const show = (0, engineConfig_1.getEngineRuntimeSettings)().showTryItMenu;
312
+ res.json({ show, demos: show === "off" ? [] : (0, bundledKrl_1.listTryItDemos)(baseUrl) });
313
+ }
314
+ catch (err) {
315
+ next(err);
316
+ }
317
+ });
305
318
  app.post("/api/stage-krl", function (req, res, next) {
306
319
  var _a, _b;
307
320
  try {
@@ -344,6 +357,7 @@ function server(core, uiECI, auth, oauth, identity) {
344
357
  version: engineVersion,
345
358
  hasRoots,
346
359
  allowSelfSignup: auth ? auth.allowSelfSignup() : false,
360
+ showTryItMenu: (0, engineConfig_1.getEngineRuntimeSettings)().showTryItMenu,
347
361
  };
348
362
  if (!auth) {
349
363
  base.eci = uiECI;
@@ -358,7 +358,8 @@ ruleset io.picolabs.xmlui {
358
358
  * Applies the theme stored in this browser tab (sessionStorage
359
359
  * picoViewTheme: default, dark, green, green-dark, gray, gray-dark) to
360
360
  * its children, on the theme's page background so rows stay readable
361
- * in dark tones.
361
+ * in dark tones. The padding keeps content off the panel's edge, which
362
+ * shows in dark tones.
362
363
  * @component
363
364
  */
364
365
  picoTheme = function() {
@@ -367,7 +368,7 @@ ruleset io.picolabs.xmlui {
367
368
  <Theme
368
369
  themeId="{['green', 'green-dark'].includes(sessionStorage.getItem('picoViewTheme') || 'default') ? 'xmlui-green' : ['gray', 'gray-dark'].includes(sessionStorage.getItem('picoViewTheme') || 'default') ? 'xmlui-gray' : 'xmlui'}"
369
370
  tone="{(sessionStorage.getItem('picoViewTheme') || 'default').endsWith('dark') ? 'dark' : 'light'}">
370
- <VStack gap="$space-2" backgroundColor="$backgroundColor">
371
+ <VStack gap="$space-2" padding="$space-3" backgroundColor="$backgroundColor">
371
372
  <Slot />
372
373
  </VStack>
373
374
  </Theme>
@@ -28,7 +28,7 @@ Engine and wrangler stay **domain-agnostic**. If a change needs the words "owner
28
28
  | `docs/design/` | Design docs (schemas, identity, move, relationships, harness) |
29
29
  | `docs/release/` | Per-release plans (`1.8.md`) and notes (`1.7.0.md`) |
30
30
  | `MEMORY.md` | Long-running working log: roadmap, decisions, gotchas. Source of truth for *why*; skim the TOC |
31
- | `test-rulesets/`, `demos/` | KRL used by tests and demos |
31
+ | `test-rulesets/`, `demos/` | KRL used by tests and demos. Each `demos/<name>/` has a README; its overview and instructions are in `docs/cookbook/<name>/` |
32
32
 
33
33
  Sibling repos (same org, not in this tree): `manifold-api` (Manifold KRL), `sensor-network`, `MCPforEXP`, `pico-framework` (lifecycle/channels/LevelDB; engine depends on `^0.8.2` for 1.8 policy ceiling).
34
34
 
@@ -72,7 +72,7 @@ rule name {
72
72
  | `raise wrangler event "child_deletion_request" attributes {"eci": picoId}` | legacy `wrangler child_deletion` with `{"id": …}` (never runs) |
73
73
  | `wrangler:picoQuery` (works over family channels) | `wrangler:skyQuery` (deprecated; HTTP blocked on family channels) |
74
74
 
75
- Also: `if X then noop(); fired { … }` runs `fired` when X is **true**. Rules in one ruleset selecting the same event run in **rule-name lexicographic order**; across rulesets the order is undefined. A stray character after `meta { }` silently prevents registration — if a ruleset never seems to run, check it actually loaded.
75
+ Also: `if X then noop(); fired { … }` runs `fired` when X is **true**. Rules in one ruleset selecting the same event run in **source order** (the order they're written), and `last` stops only the rest of that ruleset; across rulesets the order is undefined. A stray character after `meta { }` silently prevents registration — if a ruleset never seems to run, check it actually loaded.
76
76
 
77
77
  Terminology: **relationships** (1.6.2+; "subscriptions" in older code and docs). Channels have **ECIs** and **policies**; policy is the authorization gate. Every pico has a `discovery` channel.
78
78
 
@@ -80,6 +80,7 @@ Terminology: **relationships** (1.6.2+; "subscriptions" in older code and docs).
80
80
 
81
81
  - Design before code for anything touching identity, policy, schema, or the Sky API: add or update a doc in `docs/design/` and link it from `MEMORY.md`.
82
82
  - Keep `MEMORY.md` current when you learn an engine behavior the hard way; it is what future sessions read.
83
+ - View markup in KRL heredocs: put `<Component …>` on its own line after `<<`, not `<<<Component`. XMLUI accepts the leading newline.
83
84
  - Don't commit or publish; leave that to the maintainer. `npm run publish` builds and publishes every package — never run it.
84
85
  - Tests are ava, serial for engine suites (`--serial`, 2–3 min timeouts). Add a focused `test:*` script when you add a suite.
85
86
  - UI changes need `npm run build` (repo root) or `npm run dev` in `pico-engine-ui` or they won't appear in `public/`.
@@ -81,6 +81,7 @@ Example templates: [`config.example.json`](../../config.example.json), [`config.
81
81
  | `logToStdout` | boolean | Log to stdout instead of a file. Use on Fargate (set `logToStdout: true` in config). |
82
82
  | `logFile` | string | Absolute log path when `logToStdout` is false. Values `stdout`, `-`, or `0` force stdout. |
83
83
  | `logMirror` | boolean | When **`logToStdout`** is true: also write structured JSON lines to **`$PICO_ENGINE_HOME/pico-engine.log`** for operators. Default **`true`**. Set **`false`** on EFS + Fargate to avoid mirror-file churn (then use CloudWatch from stdout, or set **`logFile`** to a writable path). The Developer UI **Logging** tab reads an in-memory ring and does not need this file. **Env:** `PICO_ENGINE_LOG_MIRROR` (`true`/`1` / `false`/`0`). |
84
+ | `show_tryit_menu` | string | Where the Developer UI shows the **Try It!** tab: **`off`** (nowhere, and `/api/try-it` lists no demos), **`root_only`** (the root pico only), or **`all`** (every pico). Default **`root_only`**. **Env:** `PICO_ENGINE_SHOW_TRYIT_MENU`. |
84
85
  | `defaultRootPolicyCeiling` | object | Max channel policy for new root picos (`eventPolicy` / `queryPolicy`). See policy example file. |
85
86
  | `globalEventDeny` | array | Extra deny rules applied on **every** ECI before channel policy (e.g. block `engine:secret_ping`). |
86
87
  | `globalQueryDeny` | array | Same for queries. |
@@ -105,6 +106,8 @@ These env overrides cover config path, data dir, port, public URL, and a few log
105
106
  | `PICO_ENGINE_LOG_FILE` | Log file path, or `stdout` / `-` / `0` / empty for stdout-only |
106
107
  | `PICO_ENGINE_LOG_MIRROR` | When stdout-only: `false` / `0` disables writing `$PICO_ENGINE_HOME/pico-engine.log` (config: **`logMirror`**). The Logging tab does not read that file |
107
108
  | `PICO_ENGINE_LOG_RING` | How many recent transactions per pico the Logging tab keeps in memory. Default **200**. A restart clears the ring |
109
+ | `PICO_ENGINE_SHOW_TRYIT_MENU` | `off`, `root_only` (default), or `all`: where the Developer UI shows the **Try It!** tab (config: **`show_tryit_menu`**) |
110
+ | `PICO_ENGINE_DEMOS_DIR` | A directory to serve as `demos/` (at `/krl/demos/`) instead of the copy shipped with the engine, such as the `demos/` folder of a pico-engine checkout you're editing |
108
111
 
109
112
  ---
110
113
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pico-engine",
3
- "version": "1.9.4",
3
+ "version": "1.9.5",
4
4
  "description": "Node.js runtime for picos: persistent actors with their own identity, state, and channels that communicate by events and queries. Behavior is written in KRL. Includes an MCP server so AI coding assistants can inspect and drive a running engine.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -30,6 +30,7 @@
30
30
  ],
31
31
  "files": [
32
32
  "bin",
33
+ "demos",
33
34
  "public",
34
35
  "src",
35
36
  "krl",
@@ -45,7 +46,8 @@
45
46
  },
46
47
  "scripts": {
47
48
  "build": "rm -rf dist && tsc",
48
- "prepack": "node scripts/bundle-docs.js",
49
+ "prepack": "node scripts/bundle-docs.js && node scripts/bundle-demos.js",
50
+ "postpack": "node scripts/bundle-demos.js --clean",
49
51
  "start": "npm run dev -s",
50
52
  "dev": "scriptsp -r dev:tsc dev:api",
51
53
  "dev:tsc": "tsc -w --preserveWatchOutput",
@@ -78,6 +80,7 @@
78
80
  "test:epic9": "ava reset-cache && ava --serial ./test/epic9Matrix.ts --timeout=3m",
79
81
  "test:peer-did4": "ava reset-cache && ava --serial ./test/peerDid4.ts --timeout=2m",
80
82
  "test:views": "ava reset-cache && ava --serial ./test/xmluiSpike.ts ./test/xmluiRoutes.ts ./test/xmluiLauncher.ts ./test/xmluiConfig.ts ./test/xmluiViewSchema.ts ./test/xmluiViewPolicy.ts ./test/xmluiViewsOAuth.ts ./test/xmluiS2Demos.ts ./test/xmluiComponents.ts --timeout=2m",
83
+ "test:try-it": "ava reset-cache && ava --serial ./test/tryIt.ts ./test/tryItDemos.ts --timeout=2m",
81
84
  "vendor:xmlui": "node scripts/copy-xmlui-runtime.mjs"
82
85
  },
83
86
  "dependencies": {
@@ -140,5 +143,5 @@
140
143
  "!test/helpers/**/*"
141
144
  ]
142
145
  },
143
- "gitHead": "e7b5699ce223e802b8d2b68f78f3a87bd369b273"
146
+ "gitHead": "86e860664bb60d22c76656bc7c93b14d878405e1"
144
147
  }
Binary file