@lowdefy/docs-content 7.0.0 → 7.2.0
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.
- package/content/actions/login.md +1 -1
- package/content/actions/posthoginit.md +1 -1
- package/content/actions/resetvalidation.md +2 -0
- package/content/actions/setstate.md +0 -2
- package/content/actions/validate.md +1 -1
- package/content/adapter-reference/mongodbauthadapter.md +2 -2
- package/content/agents/agents-introduction.md +41 -1
- package/content/callback-reference/auth0logoutcallback.md +1 -1
- package/content/concepts/ai-agent-docs.md +118 -110
- package/content/concepts/blocks.md +1 -1
- package/content/concepts/connections-and-requests.md +8 -8
- package/content/concepts/custom-html.md +1 -1
- package/content/concepts/dynamic-page-content.md +26 -15
- package/content/concepts/events-and-actions.md +24 -0
- package/content/concepts/logger.md +1 -1
- package/content/concepts/lowdefy-api.md +81 -14
- package/content/concepts/lowdefy-schema.md +11 -0
- package/content/concepts/mobile-apps.md +110 -0
- package/content/concepts/page-and-app-state.md +2 -2
- package/content/concepts/theming.md +1 -1
- package/content/connections/axioshttp.md +1 -1
- package/content/connections/mongodb.md +22 -6
- package/content/controls/reject.md +2 -2
- package/content/deployment/vercel.md +1 -1
- package/content/display-blocks/aggrid.md +4 -4
- package/content/display-blocks/search.md +86 -2
- package/content/display-blocks/table.md +154 -9
- package/content/input-blocks/tableinput.md +12 -4
- package/content/input-blocks/tiptapinput.md +3 -2
- package/content/input-blocks/tiptapmentioninput.md +3 -2
- package/content/migration/v3-to-v4.md +2 -2
- package/content/operators/_base64.md +2 -2
- package/content/operators/_log.md +1 -1
- package/content/operators/_ref.md +6 -6
- package/content/plugins/plugins-introduction.md +13 -0
- package/content/plugins/posthog.md +1 -1
- package/content/provider-reference/auth-js-providers.md +2 -2
- package/content/provider-reference/openidconnectprovider.md +1 -1
- package/content/reference/cli.md +164 -0
- package/content/testing/config-tests.md +4 -4
- package/content/testing/journey-data-sets.md +21 -21
- package/content/tutorial/tutorial-create-page.md +1 -1
- package/content/tutorial/tutorial-requests-api.md +1 -1
- package/content/tutorial/tutorial-requests-sql.md +1 -1
- package/content/tutorial/tutorial-start.md +1 -1
- package/content/user-authentication/auth-configuration.md +9 -9
- package/content/user-authentication/auth-steps.md +4 -2
- package/content/user-authentication/organizations.md +57 -0
- package/content/user-authentication/protected-pages-apis.md +4 -4
- package/content/user-authentication/roles.md +2 -2
- package/content/user-authentication/user-object.md +1 -1
- package/content/websockets/websocket-publish.md +1 -1
- package/content/websockets/websockets-introduction.md +1 -1
- package/hazards.json +0 -12
- package/index.json +365 -117
- package/package.json +3 -2
- package/scripts/collectImportedFiles.js +80 -0
- package/scripts/recordSourceHashes.js +9 -6
- package/content/learn/showcase.md +0 -8
package/content/actions/login.md
CHANGED
|
@@ -28,7 +28,7 @@ The `callbackUrl` parameter of the Login action specifies where the user lands a
|
|
|
28
28
|
|
|
29
29
|
If none of the three resolves - an app with no `homePageId` whose menu offers the signed-out user no page to fall back on - the action throws rather than staying silently on the sign-in page.
|
|
30
30
|
|
|
31
|
-
To sign in without navigating at all, set `callbackUrl: false`. This is for a login form in a modal or an embedded panel
|
|
31
|
+
To sign in without navigating at all, set `callbackUrl: false`. This is for a login form in a modal or an embedded panel: the page renders the new user in place, as the server resolves them, before the next action in the chain runs. It is not valid for magic-link or social/OAuth sign-in, which redirect through a hop Lowdefy does not control.
|
|
32
32
|
|
|
33
33
|
A sign-in the auth server rejects - a wrong password, an expired or already-used link, an invalid code - is an expected outcome, not an app error. The action throws a `UserError`: `catch` actions on the event still run and the error message still displays, but it is logged to the browser console only and is never reported to the server. The auth server's response is available to `catch` actions as `_actions.<actionId>.error.metaData`, with a `code` (for example `INVALID_EMAIL_OR_PASSWORD`) and the HTTP `status`. A network failure or a server fault is still thrown as an action error and reported.
|
|
34
34
|
|
|
@@ -20,7 +20,7 @@ Every event carries the deployment environment: when the app declares [`config.e
|
|
|
20
20
|
|
|
21
21
|
Events carry Lowdefy semantics. Autocaptured clicks, rage clicks and dead clicks get `lowdefy_page_id`, `lowdefy_block_id`, `lowdefy_block_type`, `lowdefy_block_ids` (every enclosing block, innermost first), `lowdefy_option: true` on a dropdown option, `lowdefy_text` (the text of the control the click reached, such as a button or menu item, even when the click landed on its icon or a wrapper) and, inside a grid, `lowdefy_row` and `lowdefy_column`. Every other event gets `lowdefy_page_id`. This adds properties only, never events, and has no switch. A block with the `ph-no-capture` class is not autocaptured, so it is never enriched.
|
|
22
22
|
|
|
23
|
-
Click text that shows the app's data never leaves the browser. On every event, a clicked text (`$el_text`, `lowdefy_text`, the `text` entries of `$elements_chain` and `$elements`, `$selected_content` and link targets) is kept only when the config of the page, the menus, the i18n messages or the antd locale spell it out, so grid and table cell values, options and menu items a request fills, labels built from records and `Dynamic` block output are removed, while button titles, menu and tab labels, column headers, literal options and modal __OK__ and __Cancel__ stay. Element attributes other than the tag, classes, `class`, `role`, `type`, `row-index`, `col-id`, `nth-child` and `nth-of-type` are removed, including `title`, `aria-label`, `value`, `placeholder`, `alt` and `data-*`, and `id` is kept only as a block wrapper id (`bl-<blockId>`). Classes and `data-ph-capture-attribute-<name>` values (sent as property `<name>`) are not masked, so never build them from data. The other `lowdefy_*` properties stay, so a click on data still records its block, row and column. URLs are not masked: `$current_url`, `$pathname`, query values and `lowdefy_path_params` are sent unchanged. Set `maskDataText: false` to send full click text, or `options.mask_all_text: true` to send none. A block `class` of `ph-sensitive` masks that block's config text too, but only within the block's own DOM: popups it renders into the page body (`Dropdown` and `DropdownButton` items, table and grid `MenuCell` menus, `Modal`, `Drawer`) are outside it. Session replay is not covered: set `options.session_recording.maskTextSelector: '*'` to mask all text in recordings, or give a block a `class` of `ph-mask`. See [Click text masking](/PostHog#click-text-masking).
|
|
23
|
+
Click text that shows the app's data never leaves the browser. On every event, a clicked text (`$el_text`, `lowdefy_text`, the `text` entries of `$elements_chain` and `$elements`, `$selected_content` and link targets) is kept only when the config of the page, the menus, the i18n messages or the antd locale spell it out, so grid and table cell values, options and menu items a request fills, labels built from records and `Dynamic` block output are removed, while button titles, menu and tab labels, column headers, literal options and modal __OK__ and __Cancel__ stay. Element attributes other than the tag, classes, `class`, `role`, `type`, `row-index`, `col-id`, `data-row-index`, `data-col-key`, `nth-child` and `nth-of-type` are removed, including `title`, `aria-label`, `value`, `placeholder`, `alt` and other `data-*`, and `id` is kept only as a block wrapper id (`bl-<blockId>`). Classes and `data-ph-capture-attribute-<name>` values (sent as property `<name>`) are not masked, so never build them from data. The other `lowdefy_*` properties stay, so a click on data still records its block, row and column. URLs are not masked: `$current_url`, `$pathname`, query values and `lowdefy_path_params` are sent unchanged. Set `maskDataText: false` to send full click text, or `options.mask_all_text: true` to send none. A block `class` of `ph-sensitive` masks that block's config text too, but only within the block's own DOM: popups it renders into the page body (`Dropdown` and `DropdownButton` items, table and grid `MenuCell` menus, `Modal`, `Drawer`) are outside it. Session replay is not covered: set `options.session_recording.maskTextSelector: '*'` to mask all text in recordings, or give a block a `class` of `ph-mask`. See [Click text masking](/PostHog#click-text-masking).
|
|
24
24
|
|
|
25
25
|
When a block or app event fails, `PostHogInit` captures a `lowdefy_event_failed` event with `lowdefy_event_scope` (`page` or `app`), `lowdefy_page_id`, `lowdefy_block_id`, `lowdefy_block_type`, `lowdefy_event_name`, `lowdefy_debounce_ms`, `lowdefy_action_id`, `lowdefy_action_type`, `lowdefy_error_name`, `lowdefy_config_key` and `lowdefy_invalid_blocks` (the blocks a `Validate` found invalid). It carries ids only, never error messages or values, and is timestamped when the event's actions started. Failures in the app's `onInit` and in the first page's `onInit` are captured too, although `PostHogInit` runs later in `onInitAsync`: Lowdefy holds up to 20 failures until PostHog starts. At most 50 are captured per app load, held failures included. Set `captureEventFailures: false` to turn it off.
|
|
26
26
|
|
|
@@ -16,6 +16,8 @@ By default when a page is opened, no validation flags are set on any input field
|
|
|
16
16
|
|
|
17
17
|
The `ResetValidation` action `blockIds` or `regex` params are used to limit which blocks validation errors and warnings should be reset.
|
|
18
18
|
|
|
19
|
+
A container's blockId matches the container and every block inside it, so `params: contact_card` lowers the validation flags of the inputs in the `contact_card` card. A blockId that matches no block logs a warning in the browser console.
|
|
20
|
+
|
|
19
21
|
When the action runs in a list row, `$` in a blockId is replaced with the row index, as in `SetState` and `CallMethod`, so `list.$.name` matches the `name` input in the same row. `$` in a `regex` pattern keeps its regex meaning.
|
|
20
22
|
|
|
21
23
|
#### Parameters
|
|
@@ -8,8 +8,6 @@ The `SetState` action sets values in `state`. It takes an object as parameters,
|
|
|
8
8
|
This is useful if you want to initialize `state`, set a flag after an action has executed (eg. to disable a button), or to set the result
|
|
9
9
|
of a request to state.
|
|
10
10
|
|
|
11
|
-
Setting a parent object to `{}` or `null` does not clear an input that is hidden at that moment. A hidden input's value is removed from `state` but kept by the input, so the input writes its old value back when it shows again. To clear a form that has hidden inputs, set each input's own key, for example `contact.name: null`.
|
|
12
|
-
|
|
13
11
|
#### Parameters
|
|
14
12
|
|
|
15
13
|
###### object
|
|
@@ -17,7 +17,7 @@ The first time a `Validate` action is called, validation errors and warnings are
|
|
|
17
17
|
|
|
18
18
|
The `Validate` action `blockIds` or `regex` params are used to limit which blocks are validated. Only the matched blocks will be validated, and validation results are shown for only those matched blocks.
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
A container's blockId matches the container and every block inside it, so `params: contact_card` validates the inputs in the `contact_card` card. Matching follows the blocks on the page, not id prefixes, so it reaches `contact.name` inside `contact_card`. A blockId that matches no block logs a warning in the browser console and the action succeeds.
|
|
21
21
|
|
|
22
22
|
When the action runs in a list row, `$` in a blockId is replaced with the row index, as in `SetState` and `CallMethod`, so `list.$.name` matches the `name` input in the same row. `$` in a `regex` pattern keeps its regex meaning.
|
|
23
23
|
|
|
@@ -18,7 +18,7 @@ If you are upgrading from the old `MongoDBAdapter`: the type is renamed, `databa
|
|
|
18
18
|
###### Minimum configuration.
|
|
19
19
|
|
|
20
20
|
```yaml
|
|
21
|
-
lowdefy:
|
|
21
|
+
lowdefy: 7.1.0
|
|
22
22
|
auth:
|
|
23
23
|
database:
|
|
24
24
|
id: auth_db
|
|
@@ -31,7 +31,7 @@ auth:
|
|
|
31
31
|
###### Full configuration.
|
|
32
32
|
|
|
33
33
|
```yaml
|
|
34
|
-
lowdefy:
|
|
34
|
+
lowdefy: 7.1.0
|
|
35
35
|
auth:
|
|
36
36
|
database:
|
|
37
37
|
id: auth_db
|
|
@@ -9,7 +9,7 @@ Agents are defined at the root of your Lowdefy configuration, alongside `connect
|
|
|
9
9
|
A connection, an agent, and a chat block — that's all you need:
|
|
10
10
|
|
|
11
11
|
```yaml
|
|
12
|
-
lowdefy:
|
|
12
|
+
lowdefy: 7.1.0
|
|
13
13
|
|
|
14
14
|
connections:
|
|
15
15
|
- id: anthropic
|
|
@@ -65,6 +65,7 @@ Agents are defined in the top-level `agents` array in your Lowdefy configuration
|
|
|
65
65
|
- `mcp: array`: MCP server tools. See [MCP Tools](/agent-mcp-tools).
|
|
66
66
|
- `agents: array`: Sub-agent tools. See [Multi-Agent](/agent-multi-agent).
|
|
67
67
|
- `hooks: object`: Server-side lifecycle hooks. See [Server Hooks](/agent-server-hooks).
|
|
68
|
+
- `redact: object`: Patterns the server masks in the user's messages. See Redacting User Messages below. __Operators are evaluated__.
|
|
68
69
|
|
|
69
70
|
###### Agent with tools, sub-agents, and hooks:
|
|
70
71
|
```yaml
|
|
@@ -92,6 +93,45 @@ agents:
|
|
|
92
93
|
- save-conversation
|
|
93
94
|
```
|
|
94
95
|
|
|
96
|
+
## Redacting User Messages
|
|
97
|
+
|
|
98
|
+
`redact` masks text in the user's messages on the server before anything else sees it: the model, title generation, tools and the [server hooks](/agent-server-hooks) that save the conversation. Use it to keep personal information, like ID numbers or email addresses a user pastes into the chat, away from the AI provider and out of chat history, as data protection laws such as POPIA or GDPR require.
|
|
99
|
+
|
|
100
|
+
- `redact: object`:
|
|
101
|
+
- `patterns: array`: __Required__ - The patterns to mask, at least one. Each is a regular expression string, or an object:
|
|
102
|
+
- `pattern: string`: __Required__ - The regular expression.
|
|
103
|
+
- `name: string`: A name for the pattern. The server's debug log counts replacements by name, never logging the matched text.
|
|
104
|
+
- `flags: string`: Regular expression flags, such as `i`. `g` is always added, so every match is masked. The sticky flag `y` is refused.
|
|
105
|
+
- `replacement: string`: Default: `'[removed]'` - The text each match is replaced with.
|
|
106
|
+
|
|
107
|
+
The server masks the text of every user message, not only the newest: the browser sends the whole conversation with each turn. The model's replies, tool calls and results, and attached files are left as they are. `redact` applies to chat turns: a sub-agent's `redact` is not applied when another agent calls it, and the `CallAgent` routine step does not use it. The chat in the browser still shows what the user typed. A conversation the browser saves through its own endpoints is not masked by `redact`, so mask it in those endpoints too, for example with [`_string.replace`](/_string).
|
|
108
|
+
|
|
109
|
+
The patterns can come from a module var, resolved at build, or from a runtime operator such as `_secret`, evaluated with each request. The build checks a pattern written in the config; a pattern an operator returns is checked when the request runs, and an invalid one fails the turn with a config error. A pattern that matches empty text, such as `\d*`, is refused, since it would put the replacement between every character.
|
|
110
|
+
|
|
111
|
+
Patterns run in the order they are listed, each on the text the ones before it left. Put the longer patterns first: listed before an ID number pattern, a short pattern such as `\d{4}` would split the number into blocks and leave its last digits. Avoid patterns that can match the replacement text itself, like `\w+`.
|
|
112
|
+
|
|
113
|
+
###### Mask ID numbers, phone numbers and email addresses (POPIA):
|
|
114
|
+
```yaml
|
|
115
|
+
agents:
|
|
116
|
+
- id: support_agent
|
|
117
|
+
type: ClaudeAgent
|
|
118
|
+
connectionId: anthropic
|
|
119
|
+
properties:
|
|
120
|
+
model: claude-sonnet-4-20250514
|
|
121
|
+
redact:
|
|
122
|
+
replacement: '[removed]'
|
|
123
|
+
patterns:
|
|
124
|
+
- name: email
|
|
125
|
+
pattern: '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}'
|
|
126
|
+
- name: id_number
|
|
127
|
+
pattern: '\d(?:[ -]?\d){8,}'
|
|
128
|
+
hooks:
|
|
129
|
+
onFinish:
|
|
130
|
+
- save-conversation
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
A user who types `My ID is 8001015009087, email me at jo@example.com` reaches the model, and the `save-conversation` hook, as `My ID is [removed], email me at [removed]`.
|
|
134
|
+
|
|
95
135
|
## Beyond Chat
|
|
96
136
|
|
|
97
137
|
Agents can also run headlessly from [API endpoint routines](/api) using the `CallAgent` step — the agent loops through its tools to completion and the result lands in the routine's `_step` results, no chat UI involved. The step can pass images and documents beside its prompt with `files`. See [Running Agents As A Routine Step](/api) for details.
|
|
@@ -72,6 +72,10 @@ The dev server itself also serves the MCP endpoint over streamable HTTP at `/low
|
|
|
72
72
|
|
|
73
73
|
The `/lowdefy-docs` tools accept requests from agents and tools on your machine and from the dev app's own pages; a request a browser makes on behalf of another website is refused.
|
|
74
74
|
|
|
75
|
+
## Tool usage log
|
|
76
|
+
|
|
77
|
+
`lowdefy mcp` appends one line per tool call to `~/.lowdefy/tool-calls.jsonl` (under `LOWDEFY_HOME` when that is set): `{ "tool", "app", "ts", "ms", "ok" }`. It records the lifecycle tools and every forwarded dev tool, across all your projects and worktrees, in one file. It holds no arguments and no results, never leaves your machine, and rolls over at 1 MB, keeping one old file as `tool-calls.jsonl.1`. Count calls per tool from it to see which tools your agents use.
|
|
78
|
+
|
|
75
79
|
## Working across projects
|
|
76
80
|
|
|
77
81
|
A session can start and query the dev servers of several projects side by side — say, an app and the shared plugin repository it uses. Pass each call the `directory` of the app it is for. Without anything set up, `lowdefy mcp` allows apps in the session's own checkout and its git worktrees; for any other app it asks you first.
|
|
@@ -87,37 +91,27 @@ This is a consent check on the tools, not a sandbox: an agent that can run shell
|
|
|
87
91
|
|
|
88
92
|
The dev server provides these tools:
|
|
89
93
|
|
|
90
|
-
| Tool
|
|
91
|
-
|
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `lowdefy_eval_operator` | Evaluate any operator expression against live page state — a REPL for config |
|
|
112
|
-
| `lowdefy_run_request` | Execute a request with a test payload, as a given `user`, to verify data shape (read-only unless opted in) |
|
|
113
|
-
| `lowdefy_run_endpoint` | Execute an Api endpoint routine with a test payload, as a given `user` or as a system context (`system: true`), to see what it returns, rejects or throws (needs `allowWriteRequests`; a `:reject` comes back as data) |
|
|
114
|
-
| `lowdefy_snapshot_state` | Capture live page state + request responses into a committable checkpoint folder |
|
|
115
|
-
| `lowdefy_load_state` | Restore a state checkpoint — headless, or a `?_checkpoint=` URL for manual testing |
|
|
116
|
-
| `lowdefy_list_state_checkpoints` | List saved state checkpoints |
|
|
117
|
-
| `lowdefy_checkpoint_to_mocks` | Convert a state checkpoint into e2e `mocks.yaml` fixtures |
|
|
118
|
-
| `lowdefy_restart` | Restart the dev server process — after editing a local plugin's server-side code, or when `build_status` looks stale. Then call `lowdefy_build_status` with `wait: true`, which answers once the server is back |
|
|
119
|
-
| `lowdefy_checkpoint` | Snapshot all config files before risky changes |
|
|
120
|
-
| `lowdefy_revert_checkpoint` | Restore config files from a checkpoint |
|
|
94
|
+
| Tool | Purpose |
|
|
95
|
+
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
96
|
+
| `lowdefy_list_types` | List ALL available types of a kind (blocks, operators, actions, connections, requests); `target: "mobile"` lists the blocks, actions and client operators a native shell carries, for mobile pages |
|
|
97
|
+
| `lowdefy_get_schema` | JSON Schema for a specific type — all properties and events |
|
|
98
|
+
| `lowdefy_get_examples` | Real YAML usage examples for a block type |
|
|
99
|
+
| `lowdefy_get_doc` | A docs page as markdown, by slug or by type name: a Lowdefy docs page, or a page this app's own plugins and modules ship |
|
|
100
|
+
| `lowdefy_search_docs` | Search the Lowdefy docs and this app's plugin and module docs. Pages are ranked by how many query words match, title matches first; each hit names its source (`core`, `plugin`, `local-plugin` or `module`), package and version, and `source` narrows the search |
|
|
101
|
+
| `lowdefy_search_icons` | Search icon names: semantic names first, then Lucide names, then the names of installed icon sets (qualified). Never invent an icon name |
|
|
102
|
+
| `lowdefy_build_status` | Current build errors and warnings (with source file locations) plus recent runtime errors from browsers and phones (`surface: "web"` or `"mobile"`) — call after every edit |
|
|
103
|
+
| `lowdefy_check` | Validate the whole app as `lowdefy build` would, without building — every page, and the prod-only checks dev shows as warnings come back as errors. Call before calling a change done |
|
|
104
|
+
| `lowdefy_get_page_config` | The fully built config for a page, or its structured build errors |
|
|
105
|
+
| `lowdefy_screenshot_page` | PNG screenshot of a rendered page (headless Chromium) for visual verification; `width`, `height` and `colorScheme: "dark"` check a phone layout or dark mode; `urlQuery` opens it at a query string; `pathParams` opens an instance of a page whose [`path`](/page-paths) has placeholders; `steps` (`{"open": "blockId"}`, `click`, `fill`, `select`, `wait`, …) run first so the capture shows an open dropdown, calendar or modal; `device` captures a phone in Lowdefy Dev instead |
|
|
106
|
+
| `lowdefy_run_journey` | Drive a page headless through declarative steps (`click`, `fill`, `goto`, `email`, `as`, `expect`, …) and assert state, visibility, text, url, title or email — verify behaviour, not just layout; `device` runs it on a phone |
|
|
107
|
+
| `lowdefy_journey_session` | The recorded dev sessions, or one as a log (one line per interaction with what the app did, e.g. `click save → Validate failed [priority]`), to write journeys from |
|
|
108
|
+
| `lowdefy_find_config` | Which yaml file (and line) defines a given page, block, or request id |
|
|
109
|
+
| `lowdefy_app_map` | The whole-app graph: every page, menu, connection, endpoint, and agent in one call |
|
|
110
|
+
| `lowdefy_inspect_state` | The LIVE state, request results, and event log of a running page — reads your open browser tab, or runs the page headless; `device` reads a phone (`expression` evaluates an operator expression against that state instead) |
|
|
111
|
+
| `lowdefy_run_request` | Execute a request with a test payload, as a given `user`, to verify data shape (read-only unless opted in) |
|
|
112
|
+
| `lowdefy_run_endpoint` | Execute an Api endpoint routine with a test payload, as a given `user` or as a system context (`system: true`), to see what it returns, rejects or throws (needs `allowWriteRequests`; a `:reject` comes back as data) |
|
|
113
|
+
| `lowdefy_device` | Phones in Lowdefy Dev: `list` the connected phones (each tab id is the `device` the other tools take) and the booted simulators and Android devices, `start` Lowdefy Dev on a simulator or emulator, `inject` a phone's next scan, photo, NFC read, dictated transcript, location, permission answer, push or network state |
|
|
114
|
+
| `lowdefy_restart` | Restart the dev server process — after editing a local plugin's server-side code, or when `build_status` looks stale. Then call `lowdefy_build_status` with `wait: true`, which answers once the server is back |
|
|
121
115
|
|
|
122
116
|
## Hazards — what the schema cannot tell you
|
|
123
117
|
|
|
@@ -127,26 +121,9 @@ A hazard is a behaviour of a type that its schema does not show, but that an age
|
|
|
127
121
|
|
|
128
122
|
Hazards come from two places. Framework-level hazards ship with `@lowdefy/docs-content` (`hazards.json`). Type-attached hazards are declared by the plugin: a block sets `meta.hazards`, a request sets `meta.hazards` on the request function, and an operator package exports a `./metas` module with `{ hazards }` per operator — see [Plugins](/plugins-introduction). Local plugins in your project use the same channel, so your own blocks can warn an agent about their own surprises.
|
|
129
123
|
|
|
130
|
-
## Annotate your app — point, draw, copy, paste
|
|
131
|
-
|
|
132
|
-
Press **Cmd+/** (macOS) or **Ctrl+/** (Windows/Linux) on any page of your running dev app. An overlay appears: hover to highlight blocks, click to select one, draw rectangles/arrows/freehand, type a comment, and batch several annotations. Hitting **Copy** (or just pressing Enter) puts an agent-readable feedback block on your clipboard — each annotation enriched with the **blockId and the exact yaml file and line** that defines it, plus **an annotated PNG screenshot of the page with your drawings on it** (saved under `.lowdefy/annotations/`, its path included in the block so the agent can view it; untick "Include annotated screenshot" to skip).
|
|
133
|
-
|
|
134
|
-
Paste it into whichever agent session you want — that explicit paste is also what keeps feedback unambiguous when you run several Claude Code sessions against one dev server. A pasted block looks like:
|
|
135
|
-
|
|
136
|
-
```
|
|
137
|
-
Feedback: 1 annotation(s) on page "orders" (/orders) — viewport 1280x800 @2x, scrollY 340
|
|
138
|
-
|
|
139
|
-
1. Element "submit_button" (pages/orders.yaml:42)
|
|
140
|
-
Ancestors: submit_button > order_form
|
|
141
|
-
Comment: Disable this while the form is submitting
|
|
142
|
-
Shapes: 1 rect around the element
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
Esc cancels; the overlay never ships to production servers. The `/lowdefy-feedback` route prefix is reserved in dev.
|
|
146
|
-
|
|
147
124
|
## Open code — Option/Alt+click jumps to the yaml
|
|
148
125
|
|
|
149
|
-
Hold **Option** (macOS) or **Alt** (Windows/Linux) and click any element in your running dev app to open the yaml that defines its block in VS Code, at the exact line. While the modifier is held, the block under the cursor shows a blue highlight with its blockId —
|
|
126
|
+
Hold **Option** (macOS) or **Alt** (Windows/Linux) and click any element in your running dev app to open the yaml that defines its block in VS Code, at the exact line. While the modifier is held, the block under the cursor shows a blue highlight with its blockId — and the cursor becomes a pointer, so you see exactly what a click will open. The dev server resolves the clicked element to its block and looks up the config source of its block — blocks inside lists resolve to the item block that defines them (runtime array indices fold back to the config's `$` placeholder), other runtime-generated blocks resolve to their nearest configured ancestor, and blocks defined in modules open the module file that defines them. Plain clicks, Option/Alt+clicks outside any block, and Cmd/Ctrl+clicks (the browser's open-in-new-tab) keep their normal behaviour. Dev server only.
|
|
150
127
|
|
|
151
128
|
## The feedback loop
|
|
152
129
|
|
|
@@ -154,7 +131,7 @@ The dev server rebuilds automatically when config changes, so an agent works in
|
|
|
154
131
|
|
|
155
132
|
1. Discover types and schemas, write or edit YAML.
|
|
156
133
|
2. Call `lowdefy_build_status` with `wait: true` (`GET /lowdefy-docs/build-status?wait=true`) — it answers once the dev server has processed your edit, rather than with the build before it. That includes a server restart or plugin install the edit needs (a new connection type, a new plugin package, a `.env` change), so the next call reaches a ready server. Did the build succeed? Errors come back with the exact source file and location. A build that fails with an internal error carries its message, stack and the config file it was resolving.
|
|
157
|
-
3. Pages are built when they are first requested,
|
|
134
|
+
3. Pages are built when they are first requested, after the config build. `build.status` covers both: it is `ok` when the config builds and no page failed its latest build, `pages_failed` when the config builds but a page failed its latest build and has not changed since (`build.failedPages` names those pages), and `error` when the config build fails. A failed page changed since its last build is not counted until it is rebuilt, since its failure may already be fixed: it is listed under `pages.changedSinceBuild`, and `wait: true` rebuilds it. `build.configStatus` is the config build's own status, whatever the pages do. With `wait: true`, build status also builds every page your edit touched (a page whose files changed since its last build, a page built before the latest config build, or a page file changed since the dev server started) and reports under `pages`: `checked` lists the pages it built, `failed` the errors of each page whose last build failed, `changedSinceBuild` pages changed on disk that the dev server has not rebuilt yet, and `unbuilt` how many pages nothing has built since the dev server started. `lowdefy_check` validates every page.
|
|
158
135
|
4. Call `lowdefy_get_page_config` to confirm the page builds, and `lowdefy_screenshot_page` to see it rendered.
|
|
159
136
|
5. Runtime errors from the browser (operator errors, block render errors) also appear in `lowdefy_build_status` under `clientErrors`, so problems that only show at runtime still reach the agent.
|
|
160
137
|
6. Server-side failures appear beside them under `serverErrors` — a request whose database filter is malformed, an endpoint step that throws, an MCP tool call or an agent tool call that fails — each with the yaml `source` (`file:line`) and `config` path that produced it, plus the `endpointId`, `requestId` and `pageId` where known. The store holds the last 50 errors and is cleared on dev server restart.
|
|
@@ -176,7 +153,7 @@ Every event carries `type` and an ISO `timestamp`. The four types:
|
|
|
176
153
|
| `client_error` | A browser reports a runtime error | The same entry `lowdefy_build_status` lists under `clientErrors` |
|
|
177
154
|
| `server_error` | A request, endpoint, MCP tool or agent tool fails on the server | The same entry `lowdefy_build_status` lists under `serverErrors` |
|
|
178
155
|
|
|
179
|
-
Events are not buffered: a client that connects after an event missed it, and should call `lowdefy_build_status` — which is derived from the same `build/buildStatus.json
|
|
156
|
+
Events are not buffered: a client that connects after an event missed it, and should call `lowdefy_build_status` — which is derived from the same `build/buildStatus.json`, plus the page builds — for the current picture. A `build` event reports the config build only, so its `status` is never `pages_failed`. Act on a `build` event with `status: "error"` immediately; `lowdefy_build_status` remains the full report.
|
|
180
157
|
|
|
181
158
|
### When a build fails, answers are marked stale
|
|
182
159
|
|
|
@@ -209,21 +186,18 @@ The check reads the nearest `AGENTS.md` or `CLAUDE.md` holding the block, from t
|
|
|
209
186
|
|
|
210
187
|
## Live state — the agent sees what you see
|
|
211
188
|
|
|
212
|
-
When you have a page open in your browser, the agent can read its **actual live state** — page state, request results, and the event log of recent actions — via `lowdefy_inspect_state`. Reproduce a problem by clicking through the app, then ask the agent to look: it inspects your exact tab, not a guess. `
|
|
189
|
+
When you have a page open in your browser, the agent can read its **actual live state** — page state, request results, and the event log of recent actions — via `lowdefy_inspect_state`. Reproduce a problem by clicking through the app, then ask the agent to look: it inspects your exact tab, not a guess. Pass `expression` (like `{"_state": "customer.name"}`) and the same tool evaluates that operator expression against the live context instead, returning `{ value, errors, source, reads }`, where `reads` names the state, request and other paths the expression read — so `_state`/`_request` binding bugs get debugged against real data. With no tab open, it runs the page headless instead.
|
|
213
190
|
|
|
214
191
|
## Pages with path parameters
|
|
215
192
|
|
|
216
|
-
A page whose [`path`](/page-paths) has placeholders, such as `tickets/{space}/{ticket_id}`, has one instance per set of values, each with its own state and requests. `lowdefy_app_map` shows each page's `path
|
|
193
|
+
A page whose [`path`](/page-paths) has placeholders, such as `tickets/{space}/{ticket_id}`, has one instance per set of values, each with its own state and requests. `lowdefy_app_map` shows each page's `path`. The tools that open or read a page take `pathParams`, an object with one value per placeholder, next to `pageId` and `urlQuery`:
|
|
217
194
|
|
|
218
195
|
```json
|
|
219
196
|
{ "pageId": "ticket", "pathParams": { "space": "support", "ticket_id": "1234" } }
|
|
220
197
|
```
|
|
221
198
|
|
|
222
|
-
- **Headless** (`lowdefy_screenshot_page`, `lowdefy_inspect_state`, `
|
|
223
|
-
- **Your open tab** (`lowdefy_inspect_state
|
|
224
|
-
- **Checkpoints**: `lowdefy_snapshot_state` keeps the instance's `pathParams` next to `urlQuery`, and `lowdefy_load_state` opens that instance.
|
|
225
|
-
- **Plain HTTP routes**: the screenshot, page-config and inspect-state routes take a page id with several segments, the GET routes take `pathParams` as JSON in the query (`?pathParams={"ticket_id":"1"}`), and the POST routes as an object in the body.
|
|
226
|
-
- **Annotations** from the in-page feedback overlay carry the `pathParams` of the instance they were made on.
|
|
199
|
+
- **Headless** (`lowdefy_screenshot_page`, `lowdefy_inspect_state`, `lowdefy_run_journey`): `pathParams` is required to open a page that has placeholders. A missing placeholder is an error that names it, returned before a browser opens.
|
|
200
|
+
- **Your open tab** (`lowdefy_inspect_state`): with `pathParams`, the tool reads that instance. With only a `pageId`, it reads the instance your tab shows for that page, or the instance of that page most recently shown when no tab is on it.
|
|
227
201
|
|
|
228
202
|
A headless capture waits for the page's full async lifecycle before it reads anything: `onInit`, `onInitAsync`, `onMount` and `onMountAsync`, every in-flight request, and the first message on each websocket subscription. A page whose data arrives through an `onMountAsync` `Request` action is therefore captured with its data, not empty. If a page has not settled within 15 seconds the result is still returned, carrying `ready: false` and a note — read that result as a snapshot of a page that was still loading, not as the page's settled state. One case escapes the wait: an event with a `debounce` is not yet marked loading during its delay, so a debounced `onMountAsync` can be captured before it runs.
|
|
229
203
|
|
|
@@ -231,7 +205,7 @@ A headless capture waits for the page's full async lifecycle before it reads any
|
|
|
231
205
|
|
|
232
206
|
The headless renderer behind `lowdefy_screenshot_page` and `lowdefy_inspect_state` authenticates as a signed-in user, so pages with `auth.public: false` render for the agent instead of bouncing to the sign-in page. That default user carries **no roles**, so a page or request gated on a role still comes back refused or empty.
|
|
233
207
|
|
|
234
|
-
To act as a specific caller, pass `user` — every tool that renders a page headless accepts it (`lowdefy_screenshot_page`, `lowdefy_run_journey`, `lowdefy_inspect_state
|
|
208
|
+
To act as a specific caller, pass `user` — every tool that renders a page headless accepts it (`lowdefy_screenshot_page`, `lowdefy_run_journey`, `lowdefy_inspect_state`), as do `lowdefy_run_request` and `lowdefy_run_endpoint`:
|
|
235
209
|
|
|
236
210
|
```json
|
|
237
211
|
{ "pageId": "users", "user": { "roles": ["admin"] } }
|
|
@@ -251,30 +225,10 @@ Every one of these tools takes `user` in the same three forms:
|
|
|
251
225
|
|
|
252
226
|
A data set user name without `data` is refused, as are a data set while a dev mock user is active and `"none"` on a data set while auth is configured. `lowdefy_run_endpoint` also takes `system: true`, which cannot be combined with `user`.
|
|
253
227
|
|
|
254
|
-
`user` applies to the headless renderer only — it is never applied to a page you open in your own browser, which carries your real session and cannot be re-identified. `lowdefy_inspect_state`
|
|
228
|
+
`user` applies to the headless renderer only — it is never applied to a page you open in your own browser, which carries your real session and cannot be re-identified. `lowdefy_inspect_state` normally prefers your open tab, so passing `user` selects the headless source instead; combining it with `source: "tab"` is an error rather than a silently ignored role.
|
|
255
229
|
|
|
256
230
|
To bypass login for the whole dev server — your own browser included — start it with a mock user instead: `lowdefy dev --mock-user '{"id":"dev","roles":["admin"]}'` (or configure `auth.dev.mockUser`). See [Auth Configuration](/auth-configuration#mock-user-for-testing-dev-server-only).
|
|
257
231
|
|
|
258
|
-
## State checkpoints — put the app in a known state
|
|
259
|
-
|
|
260
|
-
`lowdefy_snapshot_state` captures a moment — page state plus every request's recorded response — into a folder you can commit:
|
|
261
|
-
|
|
262
|
-
```
|
|
263
|
-
checkpoints/broken-refund-flow/
|
|
264
|
-
checkpoint.json # manifest
|
|
265
|
-
state.json
|
|
266
|
-
urlQuery.json
|
|
267
|
-
pathParams.json # the instance's path values, {} for a page without placeholders
|
|
268
|
-
requests/
|
|
269
|
-
get_order.json # one file per request — easy to review and edit
|
|
270
|
-
```
|
|
271
|
-
|
|
272
|
-
Loading it back (`lowdefy_load_state`) opens the instance the checkpoint was taken on, serves the recorded request data from the dev server and re-injects the page state. Three ways to use it:
|
|
273
|
-
|
|
274
|
-
- **Agent verification**: the agent restores a scenario headless and confirms its fix works against the exact data that caused the bug.
|
|
275
|
-
- **Manual testing**: `mode: registry-only` returns a URL like `http://localhost:3000/orders?_checkpoint=broken-refund-flow` — open it and the app is in that state, no clicking required.
|
|
276
|
-
- **e2e fixtures**: `lowdefy_checkpoint_to_mocks` converts a checkpoint into `mocks.yaml` entries for [e2e tests](/e2e-introduction), so "write an e2e test for this flow" starts from captured reality.
|
|
277
|
-
|
|
278
232
|
## Running requests safely
|
|
279
233
|
|
|
280
234
|
`lowdefy_run_request` executes a request with a test payload so the agent can verify the data shape a page will receive. Read-only request types (like `MongoDBFind`) always run. The page is built first when it changed since its last build, so the request that runs is the one in the config now; a page that fails to build answers `refused: true` with its `buildErrors`.
|
|
@@ -291,7 +245,7 @@ cli:
|
|
|
291
245
|
|
|
292
246
|
## Running endpoints
|
|
293
247
|
|
|
294
|
-
`lowdefy_run_endpoint`
|
|
248
|
+
`lowdefy_run_endpoint` executes an `Api` endpoint routine headlessly with a test payload, so the agent can verify what a routine returns, rejects or throws without clicking through the page that calls it:
|
|
295
249
|
|
|
296
250
|
```json
|
|
297
251
|
{ "endpointId": "create_order", "payload": { "sku": "A1" }, "user": { "roles": ["admin"] } }
|
|
@@ -367,8 +321,8 @@ A **target** is a `blockId` string, or an object that narrows the search to a co
|
|
|
367
321
|
| Target key | Meaning |
|
|
368
322
|
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
|
369
323
|
| `blockId` | The block to search inside |
|
|
370
|
-
| `row` | A grid row, zero-based as displayed (`AgGrid
|
|
371
|
-
| `column` | A grid cell in that row, by the column's `field
|
|
324
|
+
| `row` | A grid row, zero-based as displayed (`AgGrid*`, `Table`, `TableInput`); needs `blockId` |
|
|
325
|
+
| `column` | A grid cell in that row, by the column's `field`, `colId` or `key`; needs `blockId` |
|
|
372
326
|
| `text` | The visible interactive control whose text is exactly this — a button label, a tab, a menu item (`"Cat"` never matches `"Category"`) |
|
|
373
327
|
| `nth` | When several elements match, the zero-based one to use |
|
|
374
328
|
|
|
@@ -476,6 +430,75 @@ To test auth itself — sign-up, email verification, sign-in, invitations, organ
|
|
|
476
430
|
|
|
477
431
|
Journeys are also the file format of `tests/journeys/`, which `lowdefy test` runs through this same route — write the journey the agent used to verify a change, and it becomes the regression test for it.
|
|
478
432
|
|
|
433
|
+
## Phones — the same tools on Lowdefy Dev
|
|
434
|
+
|
|
435
|
+
An app's mobile pages run in Lowdefy Dev, on an iPhone simulator, an Android emulator or a real phone (`lowdefy dev --ios`, `--android` or `--lan`). Lowdefy Dev joins the dev server as a tab, as a browser tab does, so the agent reaches it with the tools it already uses: pass a phone's tab id as `device`. The phone is used as it is — on the page it shows, signed in as whoever signed in on it, against the app's real database — so `user`, `data` and the headless browser's options (`width`, `urlQuery`, …) do not apply, and a tool given a page the phone does not show says which page it does show. Steps run on the phone by block id through the engine, the way the block's own view runs them: `click`, `fill`, `select` (an option by its text), `press` (`Enter`, on the input filled last), `wait`, `screenshot` and `expect` with `state`. Any other step is refused before the first one runs.
|
|
436
|
+
|
|
437
|
+
`lowdefy_device` with `action: "list"` names the phones connected now, and the simulators and Android devices on this computer:
|
|
438
|
+
|
|
439
|
+
```json
|
|
440
|
+
{
|
|
441
|
+
"phones": [
|
|
442
|
+
{
|
|
443
|
+
"device": "6f1c…",
|
|
444
|
+
"platform": "ios",
|
|
445
|
+
"app": "com.lowdefy.dev",
|
|
446
|
+
"shell": "7.1.0",
|
|
447
|
+
"paired": false,
|
|
448
|
+
"pageId": "ticket",
|
|
449
|
+
"pathParams": {}
|
|
450
|
+
}
|
|
451
|
+
],
|
|
452
|
+
"simulators": [{ "udid": "A1B2…", "name": "iPhone 16", "runtime": "iOS-18-2" }],
|
|
453
|
+
"android": [],
|
|
454
|
+
"unavailable": []
|
|
455
|
+
}
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
`lowdefy_device` with `action: "start"` and `platform: "ios"` or `"android"` opens Lowdefy Dev on this dev server, as `lowdefy dev --ios` or `--android` does: it boots a simulator (or uses the booted one), or finds an Android phone on USB or starts the first emulator, installs the build `LOWDEFY_DEV_APP_IOS` or `LOWDEFY_DEV_APP_ANDROID` names, opens it, and returns the new phone's `device` once it joins:
|
|
459
|
+
|
|
460
|
+
```json
|
|
461
|
+
{ "action": "start", "platform": "ios" }
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
`lowdefy_screenshot_page` with `device` runs its `steps` on the phone, then captures the whole screen — system dialogs and alerts included — with `xcrun simctl io` on a simulator or `adb exec-out screencap` on an Android device. A phone paired over the network, or one the tools cannot reach (several simulators booted, a tool missing), is captured by Lowdefy Dev from the app's own view instead. The result's `capture` says which (`simctl`, `adb` or `view`), with a `note` why for `view`:
|
|
465
|
+
|
|
466
|
+
```json
|
|
467
|
+
{ "pageId": "ticket", "device": "6f1c…", "steps": [{ "click": "assign" }] }
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
`lowdefy_run_journey` with `device` runs a journey on the phone and returns the browser journey's result — `passed`, the step log, a `failure` with expected and actual, the phone's final state and the screenshots:
|
|
471
|
+
|
|
472
|
+
```json
|
|
473
|
+
{
|
|
474
|
+
"pageId": "ticket",
|
|
475
|
+
"device": "6f1c…",
|
|
476
|
+
"steps": [
|
|
477
|
+
{ "fill": { "blockId": "note", "value": "Called the customer" } },
|
|
478
|
+
{ "click": "save" },
|
|
479
|
+
{ "expect": { "state": { "path": "note", "equals": "Called the customer" } } }
|
|
480
|
+
]
|
|
481
|
+
}
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
`lowdefy_inspect_state` with `device` reads that phone's live state, as it reads a browser tab (`source: "tab"`), and never falls back to headless. With `expression`, the phone evaluates it against the page it shows:
|
|
485
|
+
|
|
486
|
+
```json
|
|
487
|
+
{ "pageId": "ticket", "device": "6f1c…", "expression": { "_state": "status" } }
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
`lowdefy_device` with `action: "inject"` fakes the phone's next device result through Lowdefy Dev, which the app's device actions read, so it works on real phones too: `scan` `{ "data" }`, `photo` `{ "base64" }`, `nfc` (the tag read), `location` `{ "latitude", "longitude" }` or a list of them as a route, `permission` with `name` and `"granted"` or `"denied"`, `network` `"online"` or `"offline"`, `push`, and `clear`. On an iOS simulator a location and a permission are also set on the simulator itself (`xcrun simctl location`, `simctl privacy`; iOS may restart the app when a permission changes), and a push — an APNs payload with `aps` — is delivered by `xcrun simctl push`, which Lowdefy Dev cannot yet do itself on other phones:
|
|
491
|
+
|
|
492
|
+
```json
|
|
493
|
+
{
|
|
494
|
+
"action": "inject",
|
|
495
|
+
"device": "6f1c…",
|
|
496
|
+
"inject": { "kind": "scan", "value": { "data": "JOB-42" } }
|
|
497
|
+
}
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
`lowdefy_list_types` with `target: "mobile"` lists the blocks, actions and client operators a mobile page can use — the ones the native shell carries, not the app's web plugins — and `lowdefy_build_status` lists a phone's runtime errors beside the browser's, marked `surface: "mobile"` with the shell version.
|
|
501
|
+
|
|
479
502
|
## Setting up a project — one command
|
|
480
503
|
|
|
481
504
|
```bash
|
|
@@ -525,38 +548,23 @@ Or register it for every project with `claude mcp add --scope user lowdefy -- np
|
|
|
525
548
|
|
|
526
549
|
## Plain HTTP routes
|
|
527
550
|
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
| Route
|
|
531
|
-
|
|
|
532
|
-
| `GET /lowdefy-docs`
|
|
533
|
-
| `GET /lowdefy-docs/
|
|
534
|
-
| `GET /lowdefy-docs/
|
|
535
|
-
| `GET /lowdefy-docs/
|
|
536
|
-
| `
|
|
537
|
-
| `GET /lowdefy-docs/
|
|
538
|
-
| `
|
|
539
|
-
| `GET /lowdefy-docs/plugin-doc/{package}` | Markdown shipped inside a plugin package |
|
|
540
|
-
| `GET /lowdefy-docs/build-status` | Current build errors/warnings + recent browser runtime errors |
|
|
541
|
-
| `GET /lowdefy-docs/events` | SSE stream of `restart`, `build`, `client_error` and `server_error` events |
|
|
542
|
-
| `GET /lowdefy-docs/page-config/{pageId}` | Fully built page config, or its build errors |
|
|
543
|
-
| `GET /lowdefy-docs/screenshot/{pageId}` | PNG screenshot of the rendered page; `?viewportWidth=390&viewportHeight=844&colorScheme=dark` sets the viewport and colour scheme |
|
|
544
|
-
| `POST /lowdefy-docs/journey` | Drive a page headless through declarative steps and assert what happens; screenshots returned as base64 |
|
|
545
|
-
| `GET /lowdefy-docs/find/{id}?pageId=` | Locate where a page/block/request id is defined |
|
|
546
|
-
| `GET /lowdefy-docs/app-map` | Whole-app graph: pages, menus, connections, endpoints, agents |
|
|
547
|
-
| `GET /lowdefy-docs/inspect-state/{pageId}` | Live state/requests/eventLog of a running page (tab or headless) |
|
|
548
|
-
| `POST /lowdefy-docs/eval-operator` | Evaluate an operator expression against live page state |
|
|
549
|
-
| `POST /lowdefy-docs/run-request` | Execute a request with a test payload (read-only unless opted in) |
|
|
550
|
-
| `POST /lowdefy-docs/run-endpoint` | Execute an Api endpoint routine with a test payload and caller (needs `allowWriteRequests`; rejects return as data) |
|
|
551
|
-
| `GET/POST /lowdefy-docs/checkpoints` + `/revert` | Config-file checkpoints |
|
|
552
|
-
| `GET/POST /lowdefy-docs/state-checkpoints` + `/snapshot`, `/load` | State & data checkpoints |
|
|
553
|
-
| `POST /lowdefy-docs/restart` | Restart the dev server process (`{reason}` optional; then `build-status?wait=true` answers once it is back) |
|
|
551
|
+
MCP is the agent interface. A few plain routes remain for the CLI, the dev app and scripts; the rest of the tools have no HTTP route:
|
|
552
|
+
|
|
553
|
+
| Route | Purpose |
|
|
554
|
+
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
555
|
+
| `GET /lowdefy-docs` | Overview and route index |
|
|
556
|
+
| `GET /lowdefy-docs/build-status` | Current build errors/warnings + recent browser runtime errors |
|
|
557
|
+
| `GET /lowdefy-docs/events` | SSE stream of `restart`, `build`, `client_error` and `server_error` events |
|
|
558
|
+
| `GET /lowdefy-docs/page-config/{pageId}` | Fully built page config, or its build errors |
|
|
559
|
+
| `POST /lowdefy-docs/journey` | Drive a page headless through declarative steps and assert what happens; screenshots returned as base64 |
|
|
560
|
+
| `GET /lowdefy-docs/find/{id}?pageId=` | Locate where a page/block/request id is defined |
|
|
561
|
+
| `POST /lowdefy-docs/restart` | Restart the dev server process (`{reason}` optional; then `build-status?wait=true` answers once it is back) |
|
|
554
562
|
|
|
555
563
|
## Local plugins
|
|
556
564
|
|
|
557
565
|
Your project's own plugins (declared under `plugins:` in `lowdefy.yaml`) are included automatically:
|
|
558
566
|
|
|
559
|
-
- Types appear in `lowdefy_list_types`
|
|
567
|
+
- Types appear in `lowdefy_list_types` listings.
|
|
560
568
|
- Block schemas are derived from each block's `meta`, and connection/request schemas from the `schema` property on your connection and request definitions.
|
|
561
569
|
- Ship a `gallery.yaml` or `examples.yaml` next to a block in your plugin's `dist/blocks/{BlockName}/` and it is served by `lowdefy_get_examples`.
|
|
562
570
|
- A `README.md` and `docs/*.md` files in your plugin package are searched by `lowdefy_search_docs` and read with `lowdefy_get_doc` (`plugins/<package>` for the README, `plugins/<package>/<file>` for a docs file). A docs file named after a type, such as `docs/MyBlock.md`, is the doc `lowdefy_get_doc` returns for that type. `lowdefy_get_plugin_doc` returns them all as one page.
|