codeassembly-agent-logic 0.5.0 → 0.7.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.
@@ -1,4 +1,65 @@
1
1
  [
2
+ {
3
+ "version": "0.7.0",
4
+ "date": "2026-11-21",
5
+ "sections": [
6
+ {
7
+ "title": "🎉 Features",
8
+ "audience": "all",
9
+ "items": [
10
+ {
11
+ "description": "Sets each Markdown heading in `PromptPane` by its level, with its `#` marker muted even when the heading is selected, and adds a `heading` field to `PromptSegment` that records the level and whether the segment is the marker. (#2299)",
12
+ "hash": "86c0f6f48777f7941824ab216f12c85692db470c",
13
+ "entry": 2
14
+ }
15
+ ]
16
+ },
17
+ {
18
+ "title": "🐛 Bug fixes",
19
+ "audience": "all",
20
+ "items": [
21
+ {
22
+ "description": "Fixes the issue that `PromptPane` marked Markdown heading lines, list markers, and front matter as \"Not used\", by adding the `structure` value to the exported `Coverage` union, which `buildPromptSegments` assigns to that syntax and the pane leaves unmarked. (#2299)",
23
+ "hash": "86c0f6f48777f7941824ab216f12c85692db470c",
24
+ "entry": 1
25
+ }
26
+ ]
27
+ },
28
+ {
29
+ "title": "📦 Dependencies",
30
+ "audience": "dev",
31
+ "items": [
32
+ {
33
+ "description": "Upgrades `@testing-library/jest-dom` from 7.0.1 to 8.0.0, whose only breaking change drops support for Vitest versions below 5, which the repository's Vitest 5.1.1 meets. (#2301)",
34
+ "hash": "d2c434179d5faa5b3ec36ba91ef815c299c59b02",
35
+ "entry": 1
36
+ }
37
+ ]
38
+ }
39
+ ]
40
+ },
41
+ {
42
+ "version": "0.6.0",
43
+ "date": "2026-11-19",
44
+ "sections": [
45
+ {
46
+ "title": "🎉 Features",
47
+ "audience": "all",
48
+ "items": [
49
+ {
50
+ "description": "Adds `PromptPane` and `PromptKey` to `codeassembly-agent-logic/react`, which show the whole prompt with a key and mark ambient, unused, unconverted, and comment text, leaving the text that the chart uses unmarked. (#2297)",
51
+ "hash": "69ca2afee97618c49a07c257bcf70684b58f8567",
52
+ "entry": 1
53
+ },
54
+ {
55
+ "description": "Adds the custom properties `--agent-logic-passage-background`, `--agent-logic-text-subtlest`, and `--agent-logic-unconverted` to `codeassembly-agent-logic/react/styles.css` for theming the pane, and adds `--agent-logic-font-prose`, which replaces the serif face that was hard-coded for a flow's preamble. (#2297)",
56
+ "hash": "69ca2afee97618c49a07c257bcf70684b58f8567",
57
+ "entry": 2
58
+ }
59
+ ]
60
+ }
61
+ ]
62
+ },
2
63
  {
3
64
  "version": "0.5.0",
4
65
  "date": "2026-11-19",
package/CHANGELOG.md CHANGED
@@ -2,6 +2,27 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## 0.7.0 — 2026-11-21
6
+
7
+ ### 🎉 Features
8
+
9
+ - Sets each Markdown heading in `PromptPane` by its level, with its `#` marker muted even when the heading is selected, and adds a `heading` field to `PromptSegment` that records the level and whether the segment is the marker. (#2299)
10
+
11
+ ### 🐛 Bug fixes
12
+
13
+ - Fixes the issue that `PromptPane` marked Markdown heading lines, list markers, and front matter as "Not used", by adding the `structure` value to the exported `Coverage` union, which `buildPromptSegments` assigns to that syntax and the pane leaves unmarked. (#2299)
14
+
15
+ ### 📦 Dependencies
16
+
17
+ - Upgrades `@testing-library/jest-dom` from 7.0.1 to 8.0.0, whose only breaking change drops support for Vitest versions below 5, which the repository's Vitest 5.1.1 meets. (#2301)
18
+
19
+ ## 0.6.0 — 2026-11-19
20
+
21
+ ### 🎉 Features
22
+
23
+ - Adds `PromptPane` and `PromptKey` to `codeassembly-agent-logic/react`, which show the whole prompt with a key and mark ambient, unused, unconverted, and comment text, leaving the text that the chart uses unmarked. (#2297)
24
+ - Adds the custom properties `--agent-logic-passage-background`, `--agent-logic-text-subtlest`, and `--agent-logic-unconverted` to `codeassembly-agent-logic/react/styles.css` for theming the pane, and adds `--agent-logic-font-prose`, which replaces the serif face that was hard-coded for a flow's preamble. (#2297)
25
+
5
26
  ## 0.5.0 — 2026-11-19
6
27
 
7
28
  ### 🎉 Features
package/README.md CHANGED
@@ -1,15 +1,13 @@
1
1
  <!-- section:release-notes -->
2
- ## Release notes — v0.5.0 (2026-11-19)
2
+ ## Release notes — v0.7.0 (2026-11-21)
3
3
 
4
4
  ### 🎉 Features
5
5
 
6
- - Adds six seed colour properties to `codeassembly-agent-logic/react/styles.css` (`--agent-logic-surface`, `--agent-logic-text`, `--agent-logic-accent`, `--agent-logic-global`, `--agent-logic-waiting`, and `--agent-logic-warning`), from which each component property, such as `--agent-logic-border` or `--agent-logic-selected`, derives its default, and keeps each component property available to override one part. (#2296)
7
- - Changes the default palette and tints the canvas ground with the accent seed, with dots coloured from the text and accent seeds, while React Flow's `--xy-background-color` and `--xy-background-pattern-color` still replace the ground and the dots. (#2296)
8
- - Adds a dotted underline in the global colour to an ambient instruction on the canvas, the same mark that the prompt pane gives ambient text. (#2296)
6
+ - Sets each Markdown heading in `PromptPane` by its level, with its `#` marker muted even when the heading is selected, and adds a `heading` field to `PromptSegment` that records the level and whether the segment is the marker. (#2299)
9
7
 
10
8
  ### 🐛 Bug fixes
11
9
 
12
- - Fixes the issue that a consumer's layered reset, such as Tailwind's preflight, removed the padding that React Flow gives the canvas attribution, by setting that padding in the package's `styles.css` outside any cascade layer. (#2295)
10
+ - Fixes the issue that `PromptPane` marked Markdown heading lines, list markers, and front matter as "Not used", by adding the `structure` value to the exported `Coverage` union, which `buildPromptSegments` assigns to that syntax and the pane leaves unmarked. (#2299)
13
11
  <!-- /section:release-notes -->
14
12
 
15
13
  <!-- readme-type: library -->
@@ -40,8 +38,8 @@ if (result.ok) {
40
38
  | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41
39
  | `codeassembly-agent-logic` | The config schema and its validation, the converter and coverage check, the chart description, its ELK graph (`buildElkGraph`), its layout, source marking, and the bundled examples. |
42
40
  | `codeassembly-agent-logic/agent` | `convertWithAgent`, which converts a prompt by directing an ACP agent through the conversion. |
43
- | `codeassembly-agent-logic/react` | `StatechartCanvas`, the key's entries as data (`CANVAS_KEY_ENTRIES` and the mark glyphs), and the hooks of a page that presents a chart. |
44
- | `codeassembly-agent-logic/react/styles.css` | The canvas stylesheet. |
41
+ | `codeassembly-agent-logic/react` | `StatechartCanvas`, the key's entries as data (`CANVAS_KEY_ENTRIES` and the mark glyphs), `PromptPane` and its `PromptKey`, and the hooks of a page that presents a chart. |
42
+ | `codeassembly-agent-logic/react/styles.css` | The stylesheet of the canvas and the prompt pane. |
45
43
  | `codeassembly-agent-logic/server` | `createConversionHandler`, which serves conversions on an ACP agent, and its stores. |
46
44
  | `codeassembly-agent-logic/client` | `createConversionClient`, the browser client of the routes that `createConversionHandler` serves. |
47
45
  | `codeassembly-agent-logic/job` | `createConversionJob`, which converts a prompt as a job of `@williamthorsen/toolbelt.llm`, in a page or a function. |
@@ -120,7 +118,9 @@ if (started.ok) {
120
118
 
121
119
  ## What the app supplies
122
120
 
123
- The package draws the chart; the page around it is the app's. The app renders the load controls, the inspector, the source pane, and the terminal in its own design system, and it renders the canvas's key: `StatechartCanvas` passes the marks that the chart draws to its `renderKey` prop, and `CANVAS_KEY_ENTRIES` gives each mark's name, gloss, and drawing. The app also supplies the URL of the conversions resource to `./client`'s `createConversionClient`.
121
+ The package draws the chart and the prompt; the page around them is the app's. The app renders the load controls, the inspector, and the terminal in its own design system, and it renders the canvas's key: `StatechartCanvas` passes the marks that the chart draws to its `renderKey` prop, and `CANVAS_KEY_ENTRIES` gives each mark's name, gloss, and drawing.
122
+
123
+ `PromptPane` shows the whole prompt with its key, marking the text that the chart does not use and leaving used text unmarked. It sets each Markdown heading by its level, with its `#` muted, and leaves Markdown structure, such as heading lines and list markers, unmarked. The app supplies its segments, from `buildPromptSegments`, the selected element, the passages to show, and the handler that receives a clicked passage's path. A line that the app draws from the canvas to the selected passage finds the pane's text by `data-prompt-text` and the passage by `data-passage-for`, whose value is the element's path; `PromptPane`'s doc comment lists its other attributes. `PromptKey` renders the key alone, for an app that places it outside the pane. The app also supplies the URL of the conversions resource to `./client`'s `createConversionClient`.
124
124
 
125
125
  ## Styling and theming
126
126
 
@@ -136,23 +136,24 @@ The colours come in two tiers of custom properties. The seeds are a few base col
136
136
  }
137
137
  ```
138
138
 
139
- Set the properties on `:root`, or on an ancestor of both the canvas and any key that the app renders outside it. The seeds, whose defaults [`styles.css`](src/react/styles.css) declares:
139
+ Set the properties on `:root`, or on an ancestor of the canvas, the pane, and any key that the app renders outside them. The seeds, whose defaults [`styles.css`](src/react/styles.css) declares:
140
140
 
141
141
  - `--agent-logic-surface`: the background of a state and of a label
142
142
  - `--agent-logic-text`: the text
143
143
  - `--agent-logic-accent`: selection and focus
144
- - `--agent-logic-global`, `--agent-logic-waiting`, `--agent-logic-warning`: the marks for an any-time transition, a state that waits for the user, and an unreachable state
144
+ - `--agent-logic-global`, `--agent-logic-waiting`, `--agent-logic-warning`: the marks for an any-time transition and ambient text, a state that waits for the user, and an unreachable state
145
145
 
146
146
  The component properties, which an app sets to override one part; `styles.css` states each derivation:
147
147
 
148
148
  - `--agent-logic-ambient-background`, `--agent-logic-compound-background`, `--agent-logic-hover-background`: backgrounds, from `text` (and `surface` for a compound state)
149
149
  - `--agent-logic-node-background`, `--agent-logic-tooltip-text`: from `surface`
150
- - `--agent-logic-selected-background`: from `accent` and `surface`
151
- - `--agent-logic-text-subtle`, `--agent-logic-border`, `--agent-logic-border-strong`: from `text` and `surface`
150
+ - `--agent-logic-selected-background`, `--agent-logic-passage-background`: from `accent` and `surface`; the second fills the pane's selected and shown passages
151
+ - `--agent-logic-text-subtle`, `--agent-logic-text-subtlest`, `--agent-logic-border`, `--agent-logic-border-strong`: from `text` and `surface`; the pane sets unused text in the first and comments in the second
152
+ - `--agent-logic-unconverted`: the wavy line under unconverted text, from `warning` and `text`
152
153
  - `--agent-logic-tooltip-background`: from `text`
153
154
  - `--agent-logic-focus-ring`, `--agent-logic-selected`: from `accent`
154
155
 
155
- The canvas's ground and its dots also derive from the seeds; React Flow's `--xy-background-color` and `--xy-background-pattern-color` replace them. `--agent-logic-font-code` sets the code font.
156
+ The canvas's ground and its dots also derive from the seeds; React Flow's `--xy-background-color` and `--xy-background-pattern-color` replace them. `--agent-logic-font-code` sets the code font, and `--agent-logic-font-prose` the face in which the pane and a flow's preamble quote the prompt.
156
157
 
157
158
  ## The bin
158
159
 
@@ -1,12 +1,4 @@
1
- import { isFenceCloser, matchFenceOpener } from "../source/fence.js";
2
- import { findCommentSpans } from "../source/find-comment-spans.js";
3
- const BLOCKQUOTE = /^\s*>/;
4
- const HEADING = /^ {0,3}#{1,6}(?:\s|$)/;
5
- const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s+/;
6
- const LONE_TAG = /^\s*<\/?[A-Za-z][\w-]*>\s*$/;
7
- const TABLE_ROW = /^\s*\|/;
8
- const TABLE_SEPARATOR = /^\s*\|?(?:\s*:?-+:?\s*\|)+\s*:?-*:?\s*$/;
9
- const THEMATIC_BREAK = /^ {0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/;
1
+ import { blankComments, classifyLine, findFenceClose, indentOf, skipFrontMatter, splitLines, } from "../source/prompt-lines.js";
10
2
  export function findPromptBlocks(prompt) {
11
3
  const blocks = [];
12
4
  const source = blankComments(prompt);
@@ -78,63 +70,6 @@ export function findPromptBlocks(prompt) {
78
70
  flush();
79
71
  return blocks;
80
72
  }
81
- function blankComments(prompt) {
82
- let result = '';
83
- let from = 0;
84
- for (const { start, end } of findCommentSpans(prompt)) {
85
- result += prompt.slice(from, start) + prompt.slice(start, end).replaceAll(/[^\n]/g, ' ');
86
- from = end;
87
- }
88
- return result + prompt.slice(from);
89
- }
90
- function classifyLine(lines, index) {
91
- const text = lines[index]?.text ?? '';
92
- if (matchFenceOpener(text) !== undefined)
93
- return 'fence';
94
- if (text.trim() === '')
95
- return 'blank';
96
- if (HEADING.test(text) || THEMATIC_BREAK.test(text) || LONE_TAG.test(text))
97
- return 'skip';
98
- if (TABLE_ROW.test(text)) {
99
- const next = lines[index + 1];
100
- const isHeader = next !== undefined && TABLE_SEPARATOR.test(next.text);
101
- return TABLE_SEPARATOR.test(text) || isHeader ? 'skip' : 'row';
102
- }
103
- if (LIST_ITEM.test(text))
104
- return 'item';
105
- if (BLOCKQUOTE.test(text))
106
- return 'quote';
107
- return 'text';
108
- }
109
- function findFenceClose(lines, opening) {
110
- const fence = matchFenceOpener(lines[opening]?.text ?? '');
111
- if (fence === undefined)
112
- return opening;
113
- for (let index = opening + 1; index < lines.length; index++) {
114
- if (isFenceCloser(lines[index]?.text ?? '', fence))
115
- return index;
116
- }
117
- return lines.length - 1;
118
- }
119
- function indentOf(text) {
120
- return text.length - text.trimStart().length;
121
- }
122
73
  function isLeadIn(text) {
123
74
  return !text.includes('\n') && text.trimEnd().endsWith(':');
124
75
  }
125
- function skipFrontMatter(lines) {
126
- if (lines[0]?.text !== '---')
127
- return 0;
128
- const close = lines.findIndex((line, index) => index > 0 && line.text === '---');
129
- return close === -1 ? 0 : close + 1;
130
- }
131
- function splitLines(text) {
132
- const lines = [];
133
- let start = 0;
134
- for (const [index, rawLine] of text.split('\n').entries()) {
135
- const lineText = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
136
- lines.push({ start, end: start + lineText.length, number: index + 1, text: lineText });
137
- start += rawLine.length + 1;
138
- }
139
- return lines;
140
- }
@@ -1,4 +1,4 @@
1
- /** `./react` entry: the statechart canvas, the data of its key, and the hooks of a page that presents a chart. */
1
+ /** `./react` entry: the statechart canvas, the data of its key, the prompt pane, and the hooks of a chart's page. */
2
2
  export * from './canvas/canvas-key-entries.js';
3
3
  export * from './canvas/list-chart-marks.js';
4
4
  export * from './canvas/marks.js';
@@ -15,3 +15,5 @@ export * from './hooks/useEscapeToClear.js';
15
15
  export * from './hooks/useSelection.js';
16
16
  export * from './hooks/useShowAmbient.js';
17
17
  export * from './hooks/useUnknownExample.js';
18
+ export * from './source/PromptKey.js';
19
+ export * from './source/PromptPane.js';
@@ -14,3 +14,5 @@ export * from "./hooks/useEscapeToClear.js";
14
14
  export * from "./hooks/useSelection.js";
15
15
  export * from "./hooks/useShowAmbient.js";
16
16
  export * from "./hooks/useUnknownExample.js";
17
+ export * from "./source/PromptKey.js";
18
+ export * from "./source/PromptPane.js";
@@ -0,0 +1,3 @@
1
+ import type { ReactElement } from 'react';
2
+ /** The key of the prompt pane's marks, each name drawn with the mark that it names. */
3
+ export declare function PromptKey(): ReactElement;
@@ -0,0 +1,10 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ export function PromptKey() {
3
+ return (_jsx("ul", { "aria-label": "Prompt marks", className: "prompt-key", children: KEY_ENTRIES.map(({ coverage, label }) => (_jsx("li", { className: "prompt-key__entry", children: _jsx("span", { className: `prompt-key__sample prompt-key__sample--${coverage}`, children: label }) }, coverage))) }));
4
+ }
5
+ const KEY_ENTRIES = [
6
+ { coverage: 'ambient', label: 'Ambient' },
7
+ { coverage: 'unused', label: 'Not used' },
8
+ { coverage: 'unconverted', label: 'Not converted' },
9
+ { coverage: 'comment', label: 'Comment' },
10
+ ];
@@ -0,0 +1,20 @@
1
+ import { type ReactElement } from 'react';
2
+ import type { ElementDescription } from '../../layout/describe-config.js';
3
+ import type { Span } from '../../schema/agent-logic-schema.js';
4
+ import { type PromptSegment } from '../../source/prompt-segments.js';
5
+ export interface PromptPaneProps {
6
+ segments: PromptSegment[];
7
+ selected: ElementDescription | undefined;
8
+ /** The passages to mark, the earliest of which is brought into view; the segments must be cut at their bounds. */
9
+ shownPassages?: Span[] | undefined;
10
+ /** Receives the path of the element whose passage was clicked. */
11
+ onSelect: (path: string) => void;
12
+ }
13
+ /**
14
+ * The whole prompt with its key, marking the text that the chart does not use and setting each heading by its level,
15
+ * with the selected element's or the shown passages highlighted. Its text region has `data-prompt-text`, and each
16
+ * passage `data-coverage`; a selected passage has `data-selected`, the first of them `data-passage-for` with the
17
+ * element's path, a shown passage `data-shown`, the earliest of them `data-shown-passage`, and a passage that selects
18
+ * an element `data-select-path`.
19
+ */
20
+ export declare function PromptPane({ segments, selected, shownPassages, onSelect }: PromptPaneProps): ReactElement;
@@ -0,0 +1,61 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { useEffect, useId, useRef } from 'react';
3
+ import { listElementWords } from "../../source/prompt-segments.js";
4
+ import { PromptKey } from "./PromptKey.js";
5
+ export function PromptPane({ segments, selected, shownPassages = [], onSelect }) {
6
+ const headingId = useId();
7
+ const textRef = useRef(null);
8
+ const selectedPath = selected?.path;
9
+ const sharedWords = selected === undefined ? new Set() : listElementWords(selected);
10
+ const firstSelectedStart = segments.find(({ paths }) => selectedPath !== undefined && paths.includes(selectedPath))?.start;
11
+ const firstShownStart = Math.min(...shownPassages.map(({ start }) => start));
12
+ const shownKey = shownPassages.map(({ start, end }) => `${start}-${end}`).join(',');
13
+ useEffect(() => {
14
+ const container = textRef.current;
15
+ const passage = container?.querySelector('[data-passage-for], [data-shown-passage]');
16
+ const firstLine = passage?.getClientRects()[0];
17
+ if (container === null || firstLine === undefined)
18
+ return;
19
+ const bounds = container.getBoundingClientRect();
20
+ if (firstLine.top >= bounds.top && firstLine.bottom <= bounds.bottom)
21
+ return;
22
+ container.scrollTop += firstLine.top - bounds.top - container.clientHeight * 0.3;
23
+ }, [selectedPath, shownKey]);
24
+ function handleClick(event) {
25
+ if (!(event.target instanceof Element))
26
+ return;
27
+ const path = event.target.closest('[data-select-path]')?.dataset['selectPath'];
28
+ if (path !== undefined)
29
+ onSelect(path);
30
+ }
31
+ return (_jsxs("section", { "aria-labelledby": headingId, className: "prompt-pane", children: [_jsxs("div", { className: "prompt-pane__header", children: [_jsx("h2", { id: headingId, className: "prompt-pane__heading", children: "Prompt" }), _jsx(PromptKey, {})] }), _jsx("div", { ref: textRef, onClick: handleClick, "data-prompt-text": "", className: "prompt-pane__text", children: segments.map((segment) => {
32
+ const isShown = shownPassages.some(({ start, end }) => segment.start >= start && segment.end <= end);
33
+ const isSelected = selectedPath !== undefined && segment.paths.includes(selectedPath);
34
+ const selectPath = segment.coverage === 'used'
35
+ ? segment.paths[0]
36
+ : segment.coverage === 'ambient'
37
+ ? segment.paths.find((path) => AMBIENT_PATH.test(path))
38
+ : undefined;
39
+ return (_jsx("span", { className: classifyPassage(segment, isSelected || isShown), "data-coverage": segment.coverage, "data-selected": isSelected ? '' : undefined, "data-shown": isShown ? '' : undefined, "data-select-path": selectPath, "data-passage-for": isSelected && segment.start === firstSelectedStart ? selectedPath : undefined, "data-shown-passage": isShown && segment.start === firstShownStart ? '' : undefined, children: isSelected ? boldSharedWords(segment.text, sharedWords) : segment.text }, segment.start));
40
+ }) })] }));
41
+ }
42
+ const AMBIENT_PATH = /(?:^|\.)meta\.ambient\[\d+\]$/;
43
+ const WORD = /[A-Za-z0-9]/;
44
+ function boldSharedWords(text, words) {
45
+ return text
46
+ .split(/([A-Za-z0-9]+)/)
47
+ .map((part, index) => (words.has(part.toLowerCase()) ? _jsx("b", { children: part }, index) : part));
48
+ }
49
+ function classifyPassage({ coverage, heading, text }, isHighlighted) {
50
+ const isMarked = coverage !== 'structure' && (coverage !== 'unused' || WORD.test(text));
51
+ const classes = ['prompt-pane__passage'];
52
+ if (isMarked)
53
+ classes.push(`prompt-pane__passage--${coverage}`);
54
+ if (heading !== undefined)
55
+ classes.push(`prompt-pane__passage--h${heading.level}`);
56
+ if (heading?.isMarker === true)
57
+ classes.push('prompt-pane__passage--heading-marker');
58
+ if (isHighlighted)
59
+ classes.push('prompt-pane__passage--highlighted');
60
+ return classes.join(' ');
61
+ }
@@ -1,7 +1,7 @@
1
1
  /*
2
- * Styles for the statechart canvas and the marks of its key. The colours come in two tiers of custom properties: the
3
- * seeds, declared on :root, and the component properties, each of which derives its default from the seeds. A consumer
4
- * sets either tier on :root or on an ancestor of the canvas and its key.
2
+ * Styles for the statechart canvas, the prompt pane, and the marks of their keys. The colours come in two tiers of
3
+ * custom properties: the seeds, declared on :root, and the component properties, each of which derives its default from
4
+ * the seeds. A consumer sets either tier on :root or on an ancestor of the components that it renders.
5
5
  */
6
6
 
7
7
  @import '@xyflow/react/style.css';
@@ -9,6 +9,7 @@
9
9
  :where(:root) {
10
10
  --agent-logic-accent: #2346c4;
11
11
  --agent-logic-font-code: ui-monospace, monospace;
12
+ --agent-logic-font-prose: 'Iowan Old Style', Charter, 'Source Serif 4', Georgia, ui-serif, serif;
12
13
  --agent-logic-global: #b0307f;
13
14
  --agent-logic-surface: #ffffff;
14
15
  --agent-logic-text: #1c1f24;
@@ -18,9 +19,17 @@
18
19
 
19
20
  /*
20
21
  * Each component property resolves here, on the elements that read it, rather than on :root, so that seeds set on any
21
- * ancestor of the canvas or of a key entry reach the derivation. Every rule below reads the private property.
22
+ * ancestor of the canvas, the pane, or a key entry reach the derivation. Every rule below reads the private property.
22
23
  */
23
- :where(.statechart-canvas, .arrowhead-defs, .canvas-key__swatch, .canvas-key__word, .mark-glyph) {
24
+ :where(
25
+ .statechart-canvas,
26
+ .arrowhead-defs,
27
+ .canvas-key__swatch,
28
+ .canvas-key__word,
29
+ .mark-glyph,
30
+ .prompt-pane,
31
+ .prompt-key
32
+ ) {
24
33
  --_agent-logic-ambient-background: var(
25
34
  --agent-logic-ambient-background,
26
35
  color-mix(in srgb, var(--agent-logic-text) 7%, transparent)
@@ -43,6 +52,10 @@
43
52
  color-mix(in srgb, var(--agent-logic-text) 12.5%, transparent)
44
53
  );
45
54
  --_agent-logic-node-background: var(--agent-logic-node-background, var(--agent-logic-surface));
55
+ --_agent-logic-passage-background: var(
56
+ --agent-logic-passage-background,
57
+ color-mix(in srgb, var(--agent-logic-accent) 22%, var(--agent-logic-surface))
58
+ );
46
59
  --_agent-logic-selected: var(--agent-logic-selected, var(--agent-logic-accent));
47
60
  --_agent-logic-selected-background: var(
48
61
  --agent-logic-selected-background,
@@ -52,8 +65,16 @@
52
65
  --agent-logic-text-subtle,
53
66
  color-mix(in srgb, var(--agent-logic-text) 78%, var(--agent-logic-surface))
54
67
  );
68
+ --_agent-logic-text-subtlest: var(
69
+ --agent-logic-text-subtlest,
70
+ color-mix(in srgb, var(--agent-logic-text) 72%, var(--agent-logic-surface))
71
+ );
55
72
  --_agent-logic-tooltip-background: var(--agent-logic-tooltip-background, var(--agent-logic-text));
56
73
  --_agent-logic-tooltip-text: var(--agent-logic-tooltip-text, var(--agent-logic-surface));
74
+ --_agent-logic-unconverted: var(
75
+ --agent-logic-unconverted,
76
+ color-mix(in srgb, var(--agent-logic-warning) 70%, var(--agent-logic-text))
77
+ );
57
78
  }
58
79
 
59
80
  .statechart-canvas {
@@ -356,8 +377,8 @@
356
377
  background: none;
357
378
  color: var(--agent-logic-text);
358
379
  cursor: pointer;
359
- /* The serif face in which an app's prompt pane quotes the prompt. */
360
- font-family: 'Iowan Old Style', Charter, 'Source Serif 4', Georgia, ui-serif, serif;
380
+ /* The prompt pane's face, in which the preamble quotes the prompt. */
381
+ font-family: var(--agent-logic-font-prose);
361
382
  font-size: 14px;
362
383
  line-height: 20px;
363
384
  text-align: start;
@@ -528,3 +549,156 @@
528
549
  .canvas-key__word {
529
550
  color: var(--_agent-logic-text-subtle);
530
551
  }
552
+
553
+ /* -- Prompt pane: the prompt, with marks on the exceptions to used text -- */
554
+
555
+ .prompt-pane {
556
+ display: grid;
557
+ grid-template-rows: auto minmax(0, 1fr);
558
+ block-size: 100%;
559
+ min-block-size: 0;
560
+ background: var(--agent-logic-surface);
561
+ color: var(--agent-logic-text);
562
+ }
563
+
564
+ .prompt-pane__header {
565
+ display: flex;
566
+ flex-wrap: wrap;
567
+ gap: 4px 12px;
568
+ align-items: baseline;
569
+ padding: 12px 20px 4px;
570
+ }
571
+
572
+ .prompt-pane__heading {
573
+ margin: 0;
574
+ font-size: 12px;
575
+ font-weight: 600;
576
+ line-height: 16px;
577
+ }
578
+
579
+ .prompt-pane__text {
580
+ overflow: auto;
581
+ padding: 4px 20px 40px;
582
+ font-family: var(--agent-logic-font-prose);
583
+ font-size: 16px;
584
+ line-height: 26px;
585
+ white-space: pre-wrap;
586
+ }
587
+
588
+ /* Used text is unmarked, so that the marks set apart the exceptions; pointing at a passage shows that it selects. */
589
+ .prompt-pane__passage--used,
590
+ .prompt-pane__passage--ambient {
591
+ cursor: pointer;
592
+ }
593
+
594
+ .prompt-pane__passage--used:hover {
595
+ background: var(--_agent-logic-hover-background);
596
+ text-decoration: underline solid 1px var(--_agent-logic-border-strong);
597
+ text-underline-offset: 0.25em;
598
+ }
599
+
600
+ .prompt-pane__passage--ambient:hover {
601
+ background: var(--_agent-logic-hover-background);
602
+ }
603
+
604
+ /* Each mark pairs its colour with a line style or italic, and its key sample shares the rule. */
605
+ .prompt-pane__passage--ambient,
606
+ .prompt-key__sample--ambient {
607
+ text-decoration: underline dotted 2px var(--agent-logic-global);
608
+ text-underline-offset: 0.2em;
609
+ }
610
+
611
+ .prompt-pane__passage--unused,
612
+ .prompt-key__sample--unused {
613
+ color: var(--_agent-logic-text-subtle);
614
+ text-decoration: underline dashed 1px var(--_agent-logic-border);
615
+ text-underline-offset: 0.25em;
616
+ }
617
+
618
+ .prompt-pane__passage--unconverted,
619
+ .prompt-key__sample--unconverted {
620
+ text-decoration: underline wavy 1.5px var(--_agent-logic-unconverted);
621
+ text-underline-offset: 0.3em;
622
+ }
623
+
624
+ .prompt-pane__passage--comment,
625
+ .prompt-key__sample--comment {
626
+ color: var(--_agent-logic-text-subtlest);
627
+ font-style: italic;
628
+ }
629
+
630
+ /* A selected or shown passage reads as the active text: a fill without a line of its own, over any hover. */
631
+ .prompt-pane__passage--highlighted,
632
+ .prompt-pane__passage--highlighted:hover {
633
+ background: var(--_agent-logic-passage-background);
634
+ color: var(--agent-logic-text);
635
+ }
636
+
637
+ /* An unconverted passage keeps its line, which tells the reader why the passage is shown. */
638
+ .prompt-pane__passage--highlighted:not(.prompt-pane__passage--unconverted),
639
+ .prompt-pane__passage--highlighted:not(.prompt-pane__passage--unconverted):hover {
640
+ text-decoration: none;
641
+ }
642
+
643
+ .prompt-pane__passage--highlighted.prompt-pane__passage--comment {
644
+ color: var(--_agent-logic-text-subtle);
645
+ }
646
+
647
+ /*
648
+ * A heading's larger text, set on the body text's baseline, would make its line taller; aligning it to the top keeps
649
+ * the line at the pane's line height, so that no line of the prompt moves.
650
+ */
651
+ .prompt-pane__passage--h1,
652
+ .prompt-pane__passage--h2,
653
+ .prompt-pane__passage--h3,
654
+ .prompt-pane__passage--h4,
655
+ .prompt-pane__passage--h5,
656
+ .prompt-pane__passage--h6 {
657
+ vertical-align: top;
658
+ }
659
+
660
+ .prompt-pane__passage--h1 {
661
+ font-size: 22px;
662
+ font-weight: 700;
663
+ }
664
+
665
+ .prompt-pane__passage--h2 {
666
+ font-size: 19px;
667
+ font-weight: 700;
668
+ }
669
+
670
+ .prompt-pane__passage--h3 {
671
+ font-size: 17px;
672
+ font-weight: 600;
673
+ }
674
+
675
+ .prompt-pane__passage--h4,
676
+ .prompt-pane__passage--h5,
677
+ .prompt-pane__passage--h6 {
678
+ font-weight: 600;
679
+ }
680
+
681
+ /* The marker is syntax, so it stays muted when its heading is selected or shown. */
682
+ .prompt-pane__passage.prompt-pane__passage--heading-marker {
683
+ color: var(--_agent-logic-text-subtle);
684
+ }
685
+
686
+ .prompt-key {
687
+ display: flex;
688
+ flex-wrap: wrap;
689
+ gap: 4px 12px;
690
+ margin: 0;
691
+ margin-inline-start: auto;
692
+ padding: 0;
693
+ font-size: 12px;
694
+ line-height: 16px;
695
+ list-style: none;
696
+ }
697
+
698
+ .prompt-key__entry {
699
+ margin: 0;
700
+ }
701
+
702
+ .prompt-key__sample {
703
+ font-family: var(--agent-logic-font-prose);
704
+ }
@@ -0,0 +1,18 @@
1
+ import type { Span } from '../schema/agent-logic-schema.js';
2
+ /** A span of Markdown syntax that structures the prompt rather than instructs. */
3
+ export type StructureSpan = (Span & {
4
+ kind: 'heading';
5
+ level: number;
6
+ markerEnd: number;
7
+ }) | (Span & {
8
+ kind: 'line';
9
+ }) | (Span & {
10
+ kind: 'list-marker';
11
+ });
12
+ /**
13
+ * Finds, in order, the lines that `findPromptBlocks` does not take into any block, a leading YAML front matter as one
14
+ * span, and the marker of each list item. Each span starts with its line's indent, so that the indent is not left
15
+ * marked as unused text. A heading's `markerEnd` is the offset just past its run of `#`. Text inside a fenced block or
16
+ * an HTML comment is never structure.
17
+ */
18
+ export declare function findStructureSpans(prompt: string): StructureSpan[];
@@ -0,0 +1,35 @@
1
+ import { blankComments, classifyLine, findFenceClose, HEADING, indentOf, LIST_MARKER, skipFrontMatter, splitLines, } from "./prompt-lines.js";
2
+ export function findStructureSpans(prompt) {
3
+ const spans = [];
4
+ const lines = splitLines(blankComments(prompt));
5
+ const first = skipFrontMatter(lines);
6
+ const frontMatterEnd = lines[first - 1]?.end;
7
+ if (frontMatterEnd !== undefined)
8
+ spans.push({ kind: 'line', start: 0, end: frontMatterEnd });
9
+ for (let index = first; index < lines.length; index++) {
10
+ const line = lines[index];
11
+ if (line === undefined)
12
+ break;
13
+ const { start } = line;
14
+ const markerStart = start + indentOf(line.text);
15
+ switch (classifyLine(lines, index)) {
16
+ case 'fence':
17
+ index = findFenceClose(lines, index);
18
+ break;
19
+ case 'item': {
20
+ const markerLength = LIST_MARKER.exec(line.text.trimStart())?.[0].length ?? 0;
21
+ spans.push({ kind: 'list-marker', start, end: markerStart + markerLength });
22
+ break;
23
+ }
24
+ case 'skip': {
25
+ const markerLength = HEADING.exec(line.text)?.[1]?.length;
26
+ spans.push(markerLength === undefined
27
+ ? { kind: 'line', start, end: line.end }
28
+ : { kind: 'heading', start, end: line.end, level: markerLength, markerEnd: markerStart + markerLength });
29
+ break;
30
+ }
31
+ default:
32
+ }
33
+ }
34
+ return spans;
35
+ }
@@ -0,0 +1,26 @@
1
+ /** A line of a prompt with its offsets, excluding its newline. */
2
+ export interface Line {
3
+ start: number;
4
+ end: number;
5
+ /** The 1-based line number. */
6
+ number: number;
7
+ text: string;
8
+ }
9
+ export type LineKind = 'blank' | 'fence' | 'item' | 'quote' | 'row' | 'skip' | 'text';
10
+ export declare const HEADING: RegExp;
11
+ export declare const LIST_MARKER: RegExp;
12
+ /** Replaces each HTML comment with spaces, keeping its newlines, so that offsets and line numbers stay the same. */
13
+ export declare function blankComments(prompt: string): string;
14
+ /**
15
+ * Returns what the line at the index is, as far as cutting the prompt into blocks goes. Headings, thematic breaks,
16
+ * table header and separator rows, and lines that hold only an HTML tag are `skip`, because they hold no instruction.
17
+ */
18
+ export declare function classifyLine(lines: Line[], index: number): LineKind;
19
+ /** Returns the index of the line that closes the fence opened at the index, or the last line's when nothing does. */
20
+ export declare function findFenceClose(lines: Line[], opening: number): number;
21
+ /** Returns the number of leading whitespace characters of the line. */
22
+ export declare function indentOf(text: string): number;
23
+ /** Returns the index of the first line after a YAML front matter that opens the prompt, or 0 when it has none. */
24
+ export declare function skipFrontMatter(lines: Line[]): number;
25
+ /** Splits the text into lines with their offsets, excluding each line's newline. */
26
+ export declare function splitLines(text: string): Line[];
@@ -0,0 +1,67 @@
1
+ import { isFenceCloser, matchFenceOpener } from "./fence.js";
2
+ import { findCommentSpans } from "./find-comment-spans.js";
3
+ const BLOCKQUOTE = /^\s*>/;
4
+ export const HEADING = /^ {0,3}(#{1,6})(?:\s|$)/;
5
+ const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s+/;
6
+ export const LIST_MARKER = /^(?:[-*+]|\d+[.)])/;
7
+ const LONE_TAG = /^\s*<\/?[A-Za-z][\w-]*>\s*$/;
8
+ const TABLE_ROW = /^\s*\|/;
9
+ const TABLE_SEPARATOR = /^\s*\|?(?:\s*:?-+:?\s*\|)+\s*:?-*:?\s*$/;
10
+ const THEMATIC_BREAK = /^ {0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/;
11
+ export function blankComments(prompt) {
12
+ let result = '';
13
+ let from = 0;
14
+ for (const { start, end } of findCommentSpans(prompt)) {
15
+ result += prompt.slice(from, start) + prompt.slice(start, end).replaceAll(/[^\n]/g, ' ');
16
+ from = end;
17
+ }
18
+ return result + prompt.slice(from);
19
+ }
20
+ export function classifyLine(lines, index) {
21
+ const text = lines[index]?.text ?? '';
22
+ if (matchFenceOpener(text) !== undefined)
23
+ return 'fence';
24
+ if (text.trim() === '')
25
+ return 'blank';
26
+ if (HEADING.test(text) || THEMATIC_BREAK.test(text) || LONE_TAG.test(text))
27
+ return 'skip';
28
+ if (TABLE_ROW.test(text)) {
29
+ const next = lines[index + 1];
30
+ const isHeader = next !== undefined && TABLE_SEPARATOR.test(next.text);
31
+ return TABLE_SEPARATOR.test(text) || isHeader ? 'skip' : 'row';
32
+ }
33
+ if (LIST_ITEM.test(text))
34
+ return 'item';
35
+ if (BLOCKQUOTE.test(text))
36
+ return 'quote';
37
+ return 'text';
38
+ }
39
+ export function findFenceClose(lines, opening) {
40
+ const fence = matchFenceOpener(lines[opening]?.text ?? '');
41
+ if (fence === undefined)
42
+ return opening;
43
+ for (let index = opening + 1; index < lines.length; index++) {
44
+ if (isFenceCloser(lines[index]?.text ?? '', fence))
45
+ return index;
46
+ }
47
+ return lines.length - 1;
48
+ }
49
+ export function indentOf(text) {
50
+ return text.length - text.trimStart().length;
51
+ }
52
+ export function skipFrontMatter(lines) {
53
+ if (lines[0]?.text !== '---')
54
+ return 0;
55
+ const close = lines.findIndex((line, index) => index > 0 && line.text === '---');
56
+ return close === -1 ? 0 : close + 1;
57
+ }
58
+ export function splitLines(text) {
59
+ const lines = [];
60
+ let start = 0;
61
+ for (const [index, rawLine] of text.split('\n').entries()) {
62
+ const lineText = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
63
+ lines.push({ start, end: start + lineText.length, number: index + 1, text: lineText });
64
+ start += rawLine.length + 1;
65
+ }
66
+ return lines;
67
+ }
@@ -1,6 +1,7 @@
1
1
  import type { ConfigDescription, ElementDescription } from '../layout/describe-config.js';
2
2
  import type { Span, UnconvertedSpan } from '../schema/agent-logic-schema.js';
3
- export type Coverage = 'ambient' | 'comment' | 'used' | 'unused' | 'unconverted';
3
+ /** How the chart uses a run of prompt text; `structure` is Markdown syntax, such as a heading line or a list marker. */
4
+ export type Coverage = 'ambient' | 'comment' | 'structure' | 'used' | 'unused' | 'unconverted';
4
5
  /** A run of prompt text that the same element spans cover. */
5
6
  export interface PromptSegment {
6
7
  start: number;
@@ -9,10 +10,15 @@ export interface PromptSegment {
9
10
  coverage: Coverage;
10
11
  /** Paths of the elements whose spans cover the segment, narrowest span first. */
11
12
  paths: string[];
13
+ /** The level of the Markdown heading whose line contains the segment, and whether the segment is its `#` marker. */
14
+ heading?: {
15
+ level: number;
16
+ isMarker: boolean;
17
+ };
12
18
  }
13
19
  /**
14
- * Cuts the prompt at every span, comment, and shown-span boundary into contiguous segments, each with the elements
15
- * that cover it.
20
+ * Cuts the prompt at every span, comment, structure, and shown-span boundary into contiguous segments, each with the
21
+ * elements that cover it.
16
22
  */
17
23
  export declare function buildPromptSegments(prompt: string, description: ConfigDescription, unconverted: UnconvertedSpan[], shown?: Span[]): PromptSegment[];
18
24
  /** Lists the lowercase words of an element's identifiers and prose, without common function words. */
@@ -1,4 +1,5 @@
1
1
  import { findCommentSpans } from "./find-comment-spans.js";
2
+ import { findStructureSpans } from "./find-structure-spans.js";
2
3
  export function buildPromptSegments(prompt, description, unconverted, shown = []) {
3
4
  const elements = [...description.states.filter(({ parentId }) => parentId !== undefined), ...description.transitions];
4
5
  const elementSpans = [
@@ -14,8 +15,10 @@ export function buildPromptSegments(prompt, description, unconverted, shown = []
14
15
  ];
15
16
  const ambientSpans = description.ambient.map(({ source }) => source);
16
17
  const commentSpans = findCommentSpans(prompt);
17
- const cuts = new Set([0, prompt.length]);
18
- for (const { start, end } of [...elementSpans, ...unconverted, ...commentSpans, ...shown]) {
18
+ const structureSpans = findStructureSpans(prompt);
19
+ const headings = structureSpans.filter((span) => span.kind === 'heading');
20
+ const cuts = new Set([0, prompt.length, ...headings.map(({ markerEnd }) => markerEnd)]);
21
+ for (const { start, end } of [...elementSpans, ...unconverted, ...commentSpans, ...structureSpans, ...shown]) {
19
22
  cuts.add(start);
20
23
  cuts.add(end);
21
24
  }
@@ -26,12 +29,14 @@ export function buildPromptSegments(prompt, description, unconverted, shown = []
26
29
  const end = points[index + 1] ?? prompt.length;
27
30
  const covering = elementSpans.filter((span) => span.start <= start && span.end >= end);
28
31
  const paths = covering.toSorted((a, b) => a.end - a.start - (b.end - b.start)).map(({ path }) => path);
32
+ const heading = headings.find((span) => span.start <= start && span.end >= end);
29
33
  segments.push({
30
34
  start,
31
35
  end,
32
36
  text: prompt.slice(start, end),
33
- coverage: findCoverage(start, end, { unconverted, ambient: ambientSpans, comments: commentSpans }, paths),
37
+ coverage: findCoverage(start, end, { unconverted, ambient: ambientSpans, comments: commentSpans, structure: structureSpans }, paths),
34
38
  paths,
39
+ ...(heading !== undefined && { heading: { level: heading.level, isMarker: end <= heading.markerEnd } }),
35
40
  });
36
41
  }
37
42
  return segments;
@@ -50,14 +55,16 @@ export function splitWords(text) {
50
55
  .split(/[^a-z0-9]+/)
51
56
  .filter((word) => word !== '' && !STOP_WORDS.has(word));
52
57
  }
53
- function findCoverage(start, end, { unconverted, ambient, comments }, paths) {
58
+ function findCoverage(start, end, { unconverted, ambient, comments, structure }, paths) {
54
59
  if (unconverted.some(covers))
55
60
  return 'unconverted';
56
61
  if (ambient.some(covers))
57
62
  return 'ambient';
58
63
  if (paths.length > 0)
59
64
  return 'used';
60
- return comments.some(covers) ? 'comment' : 'unused';
65
+ if (comments.some(covers))
66
+ return 'comment';
67
+ return structure.some(covers) ? 'structure' : 'unused';
61
68
  function covers(span) {
62
69
  return span.start <= start && span.end >= end;
63
70
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codeassembly-agent-logic",
3
- "version": "0.5.0",
3
+ "version": "0.7.0",
4
4
  "description": "Model of an agent prompt's states and transitions, with React and server entries for the apps that present it",
5
5
  "keywords": [
6
6
  "agents",
@@ -64,7 +64,7 @@
64
64
  ".meta/changelog.json"
65
65
  ],
66
66
  "dependencies": {
67
- "@williamthorsen/toolbelt.errors": "0.11.3",
67
+ "@williamthorsen/toolbelt.errors": "0.11.4",
68
68
  "@xyflow/react": "13.0.2",
69
69
  "elkjs": "0.12.1",
70
70
  "zod": "4.6.7"
@@ -73,16 +73,16 @@
73
73
  "@modelcontextprotocol/client": "2.4.0",
74
74
  "@modelcontextprotocol/server": "2.4.0",
75
75
  "@testing-library/dom": "10.4.2",
76
- "@testing-library/jest-dom": "7.0.1",
76
+ "@testing-library/jest-dom": "8.0.0",
77
77
  "@testing-library/react": "16.3.3",
78
- "@testing-library/user-event": "14.6.12",
78
+ "@testing-library/user-event": "14.6.13",
79
79
  "@types/node": "24.19.2",
80
80
  "@types/react": "19.3.0",
81
81
  "@types/react-dom": "19.3.0",
82
82
  "@vitejs/plugin-react": "6.3.0",
83
83
  "@williamthorsen/nmr": "2.3.0",
84
- "@williamthorsen/toolbelt.acp": "0.3.2",
85
- "@williamthorsen/toolbelt.llm": "0.2.0",
84
+ "@williamthorsen/toolbelt.acp": "0.3.3",
85
+ "@williamthorsen/toolbelt.llm": "0.2.1",
86
86
  "eslint": "10.15.0",
87
87
  "eslint-plugin-jest-dom": "5.10.2",
88
88
  "eslint-plugin-react": "7.37.5",