Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
This document summarizes notable updates since February 2025, with commit dates from the repository history for context.【728428†L1-L48】

## 2026-07
- **UX (2.1.8):** Stepping through a trace no longer redraws the page. Every trace state used to be rendered as its own copy of the formula tree, and a step cross-faded between two of them: for 250ms both copies were `display: block` inside a `flex-wrap` container, so the stepper occupied two rows and everything below it — the rule, the "different trace" button, the footer — was shoved down and snapped back on every click. The incoming copy also rebuilt its trace diagram from scratch (`TraceRenderer.render` clears the container) even though the diagram is identical at every step bar the highlight, and a 1s `flashHighlight` animation fired over the tree each time. Between the three, a step read as a page reload. Only two things actually differ between steps, so only those change now: the `tree-sat`/`tree-unsat` class on each node of a single tree, and which state carries the highlight. `TraceSatisfactionResult.getStepperViewData` sends the tree once plus one truth vector per state, addressed by a new `data-node-index` emitted in the same pre-order `getAllSubformulae` walks; `TraceRenderer.setHighlight` moves the highlight by toggling attributes on the existing SVG (every state gets a `CURRENT` badge at render time, hidden but for the current one), so nothing is created, measured or resized. Verified in the running app: document height, button position and the SVG element itself are unchanged across all steps, with no network requests. The 250ms transition also gated input — presses inside the window were dropped, so holding an arrow key lost most of them — and that guard is gone, so stepping keeps up with the keyboard. The empty stepper tab now says so, matching the Table and Matrix tabs, and the arrow buttons carry `aria-label`s rather than relying on `title` over an icon.
- **UX (2.1.8):** Removed the "No further feedback is currently available. We recommend stepping through the trace to see where/if it diverges from the formula." message from trace-satisfaction yes/no questions. It was the fallback for the half of those questions whose trace genuinely satisfies the formula (`TRACESAT_YES_PROBABILITY = 0.5`), where there is no misconception formula to contrast against — but it has been stale since per-state feedback landed in 2.1.6: it printed *below* a paragraph that already explains the verdict ("This trace **does** satisfy the formula… a trace satisfies the formula exactly when it holds from the very first state"), and its step-through recommendation duplicated the "Want to see it step by step?" stepper button below it. Such questions now carry no predetermined feedback (`feedback` is `None`; both templates already guarded on it). The "No" case keeps its contrastive feedback, which names the formula the trace *does* satisfy — something the per-state marks don't say. If the per-state block can't render (SPOT evaluation fails, or the state count doesn't match the drawn trace), `displayTraceSatFeedback` still returns silently, so those rare cases now show the verdict and the stepper button alone.
- **Bugfix (2.1.6):** The trace diagrams inside misconception explainers never rendered. Explainers are shown in the "recommended review" card on the home page, but `index.html` was the one page emitting `.trace-diagram` markup without loading `tracerenderer.js`, so the diagrams stayed empty `<div>`s — leaving the Finally explainer ending on "Thus both these traces satisfy `F p`:" followed by nothing, and the Until explainer missing the trace its closing sentence refers to. It looked intermittent because only two of the eight explainers (`implicitf`, `exclusiveu`) illustrate the operator with traces, and the card shows one explainer drawn at random from the student's top two misconceptions. The home page now loads the renderer and runs a render pass. The three copies of that pass (home page, exercise questions, answer feedback) are now one `TraceRenderer.renderAll(root)` helper, so a page that emits trace markup only has to call it.
- **UX (2.1.5):** The "unclear sentence" report control on english-to-LTL questions no longer reads as a heading for the answer options. It was a bold rust question ("Is this English sentence confusing or unclear?") sitting an equal distance from the stem above and the radio list below, so it grouped with neither; its `.row.ml-2` wrapper also pulled it left of the stem's text edge, since Bootstrap's `.row` sets `margin-left: -15px` and `ml-2` only partly cancels it. It is now a quiet caption-style link reading "Report unclear wording" (imperative, so it cannot be mistaken for the question to answer), tucked under the sentence with asymmetric spacing (about 4px above, 18px below) that groups it with the stem. Being quiet means losing the color signal, so it carries a permanent underline rather than color alone (WCAG 1.4.1), and uses `--ink-2` at 8:1 rather than the muted `--ink-3`, which is 4.17:1 on the card and under AA for small text; color returns on hover and focus. The control stays a sibling of `.actualQuestion`, so its label never leaks into the logged `question_text`. The modal, its route, and its payload are unchanged.
- **A11y (2.1.5):** The keyboard focus ring now actually appears on that control. The theme's global ring is a zero-specificity `:where(...):focus-visible` rule, which Bootstrap's `.btn:focus { outline: 0 }` outranks on any button, so the only focus signal would have been a color shift; `.btn.unclear-flag:focus-visible` restates it at (0,3,0). The letter key also uses `--ink-2` (8:1) rather than `text-muted` (`--ink-3`, 4.17:1 on the card, under AA at that size), since the key is the only place the letters in the options are defined. The rest of the page still pairs `text-muted` with `small` at that sub-AA ratio (card-header meta, question description); that is pre-existing and wants its own pass.
Expand Down
14 changes: 8 additions & 6 deletions src/app.py
Original file line number Diff line number Diff line change
Expand Up @@ -1151,29 +1151,31 @@ def ltlstepper():
syntax_choice = 'Classic'

empty_trace_data = json.dumps({"prefix": [], "cycle": []})
empty_steps = json.dumps([])

if request.method == 'GET':
return render_template('stepper.html', uid = getUserName(), error="", prefixstates=[], cyclestates=[], matrix_data={"subformulae": [], "matrix": [], "rows": []}, trace_render_data=empty_trace_data)
return render_template('stepper.html', uid = getUserName(), error="", prefixstates=[], cyclestates=[], matrix_data={"subformulae": [], "matrix": [], "rows": []}, trace_render_data=empty_trace_data, stepper_tree_html="", stepper_steps=empty_steps)

if request.method == 'POST':
ltl = request.form.get('formula')
trace = request.form.get('trace')
if ltl == "" or trace == "":
error="Please enter an LTL formula and a trace."

try:
node = parse_ltl_string(ltl)
except:
return render_template('stepper.html', uid = getUserName(), error="Invalid LTL formula " + ltl, prefixstates=[], cyclestates=[], matrix_data={"subformulae": [], "matrix": [], "rows": []}, trace_render_data=empty_trace_data)
return render_template('stepper.html', uid = getUserName(), error="Invalid LTL formula " + ltl, prefixstates=[], cyclestates=[], matrix_data={"subformulae": [], "matrix": [], "rows": []}, trace_render_data=empty_trace_data, stepper_tree_html="", stepper_steps=empty_steps)

try:
result = traceSatisfactionPerStep(node = node, trace = trace, syntax = syntax_choice)
except:
return render_template('stepper.html', uid = getUserName(), error="Invalid trace " + trace, prefixstates=[], cyclestates=[], matrix_data={"subformulae": [], "matrix": [], "rows": []}, trace_render_data=empty_trace_data)
return render_template('stepper.html', uid = getUserName(), error="Invalid trace " + trace, prefixstates=[], cyclestates=[], matrix_data={"subformulae": [], "matrix": [], "rows": []}, trace_render_data=empty_trace_data, stepper_tree_html="", stepper_steps=empty_steps)

matrix_data = result.getMatrixView()
stepper_view = result.getStepperViewData()
trace_render_data = json.dumps(getTraceRenderData(trace))
return render_template('stepper.html', uid = getUserName(), error="", prefixstates=result.prefix_states, cyclestates=result.cycle_states, formula = ltl, trace=trace, matrix_data=matrix_data, trace_render_data=trace_render_data)
return render_template('stepper.html', uid = getUserName(), error="", prefixstates=result.prefix_states, cyclestates=result.cycle_states, formula = ltl, trace=trace, matrix_data=matrix_data, trace_render_data=trace_render_data, stepper_tree_html=stepper_view["tree_html"], stepper_steps=json.dumps(stepper_view["steps"]))


##### Eng LTL Logging Routes ###
Expand Down
6 changes: 5 additions & 1 deletion src/exercisebuilder.py
Original file line number Diff line number Diff line change
Expand Up @@ -744,7 +744,11 @@ def build_tracesat_yn_question(self, answer):
parenthesized_answer = self.toSpotSyntax(answer)


feedbackString = "No further feedback is currently available. We recommend stepping through the trace to see where/if it diverges from the formula."
# Only the "No" case has a second formula to contrast against, so only it
# gets predetermined feedback. When the trace does satisfy the formula the
# question carries none: the client already explains that verdict from the
# per-state satisfaction marks, and offers the stepper below it.
feedbackString = None
# So no misconceptions forthcoming...
## TODO: Should we even generate a question one here?
if formulae is None:
Expand Down
99 changes: 82 additions & 17 deletions src/static/js/tracerenderer.js
Original file line number Diff line number Diff line change
Expand Up @@ -357,28 +357,34 @@ var TraceRenderer = (function () {
for (i = 0; i < states.length; i++) {
var s = states[i];
var hl = (s.gi === hlIdx);
var g = _el('g', {});
var stateFill = (hl ? CFG.hlFill : (s.isCycle ? CFG.cycleFill : CFG.prefixFill));
var baseFill = (s.isCycle ? CFG.cycleFill : CFG.prefixFill);
var g = _el('g', { 'data-state-index': String(s.gi) });

if (showStateIndices || marks) {
var topText = showStateIndices ? 's' + s.gi : '';
var topFill = hl ? CFG.hlStroke : CFG.indexTextFill;
var topWeight = hl ? '700' : '500';
if (marks) {
topText += (topText ? ' ' : '') + (marks[i] ? '✓' : '✗');
topFill = marks[i] ? CFG.markSatFill : CFG.markUnsatFill;
topWeight = '700';
}
var idxLabel = _el('text', {
var labelAttrs = {
'x': s.x + s.w / 2,
'y': s.y - 8,
'text-anchor': 'middle',
'dominant-baseline': 'central',
'fill': topFill,
'font-family': 'SFMono-Regular, Consolas, "Liberation Mono", Menlo, monospace',
'font-size': marks ? '13' : '11',
'font-weight': topWeight
});
'class': 'trc-state-label'
};
if (marks) {
topText += (topText ? ' ' : '') + (marks[i] ? '✓' : '✗');
topFill = marks[i] ? CFG.markSatFill : CFG.markUnsatFill;
topWeight = '700';
// Mark colors carry meaning of their own, so setHighlight
// leaves them alone.
labelAttrs['data-marked'] = '1';
}
labelAttrs['fill'] = topFill;
labelAttrs['font-weight'] = topWeight;

var idxLabel = _el('text', labelAttrs);
idxLabel.textContent = topText;
g.appendChild(idxLabel);
}
Expand All @@ -387,18 +393,28 @@ var TraceRenderer = (function () {
'x': s.x, 'y': s.y,
'width': s.w, 'height': boxH,
'rx': CFG.radius, 'ry': CFG.radius,
'fill': stateFill,
'fill': hl ? CFG.hlFill : baseFill,
'stroke': hl ? CFG.hlStroke : CFG.stroke,
'stroke-width': hl ? CFG.hlWidth : CFG.strokeW
'stroke-width': hl ? CFG.hlWidth : CFG.strokeW,
'class': 'trc-state-rect',
'data-base-fill': baseFill
}));

if (hl) {
// When a state is highlighted at all, every state gets a badge and
// only the current one is shown, so moving the highlight later is a
// visibility toggle rather than a re-render.
if (showStateIndices) {
var badgeText = 'CURRENT';
var badgeW = Math.max(52, Math.ceil(_textWidth(badgeText, CFG.indexFont)) + 12);
var badgeX = s.x + (s.w - badgeW) / 2;
var badgeY = s.y - CFG.currentBadgeH - 2;
var badge = _el('g', { 'class': 'trc-current-badge' });

g.appendChild(_el('rect', {
if (!hl) {
badge.style.display = 'none';
}

badge.appendChild(_el('rect', {
'x': badgeX,
'y': badgeY,
'width': badgeW,
Expand All @@ -419,7 +435,8 @@ var TraceRenderer = (function () {
'font-weight': '700'
});
badgeLabel.textContent = badgeText;
g.appendChild(badgeLabel);
badge.appendChild(badgeLabel);
g.appendChild(badge);
}

if (useVertical && s.tokens.length > 1) {
Expand Down Expand Up @@ -501,6 +518,54 @@ var TraceRenderer = (function () {
container.appendChild(svg);
}

/**
* Move the "current state" highlight on an already-rendered diagram.
*
* Only works on a diagram rendered with a `highlightIndex`, since that is
* what reserves room for the badge. Nothing is created, removed or
* measured, so the diagram never changes size and the page never reflows —
* which is the point: stepping through a trace should not redraw it.
*
* @param {HTMLElement} container the element `render` drew into
* @param {number} index global state index to highlight
* @returns {boolean} false if there is no diagram to update
*/
function setHighlight(container, index) {
if (!container) {
return false;
}

var groups = container.querySelectorAll('g[data-state-index]');
if (!groups.length) {
return false;
}

for (var i = 0; i < groups.length; i++) {
var g = groups[i];
var hl = (parseInt(g.getAttribute('data-state-index'), 10) === index);

var rect = g.querySelector('.trc-state-rect');
if (rect) {
rect.setAttribute('fill', hl ? CFG.hlFill : (rect.getAttribute('data-base-fill') || CFG.prefixFill));
rect.setAttribute('stroke', hl ? CFG.hlStroke : CFG.stroke);
rect.setAttribute('stroke-width', hl ? CFG.hlWidth : CFG.strokeW);
}

var label = g.querySelector('.trc-state-label');
if (label && !label.hasAttribute('data-marked')) {
label.setAttribute('fill', hl ? CFG.hlStroke : CFG.indexTextFill);
label.setAttribute('font-weight', hl ? '700' : '500');
}

var badge = g.querySelector('.trc-current-badge');
if (badge) {
badge.style.display = hl ? '' : 'none';
}
}

return true;
}

/**
* Render every not-yet-rendered `.trace-diagram[data-trace]` under `root`.
*
Expand All @@ -527,5 +592,5 @@ var TraceRenderer = (function () {
}
}

return { render: render, renderAll: renderAll };
return { render: render, setHighlight: setHighlight, renderAll: renderAll };
})();
39 changes: 36 additions & 3 deletions src/stepper.py
Original file line number Diff line number Diff line change
Expand Up @@ -68,14 +68,22 @@ def formattedTraceAssignment(self):
def formulaTreeAsHTML(self):
return f'<ul class="formula-tree">{self._build_tree_html()}</ul>'

def _build_tree_html(self):
def _build_tree_html(self, counter=None):
# data-node-index numbers the nodes in pre-order, the same order
# getAllSubformulae walks them, so the stepper can address a node by
# its position in a state's truth vector.
if counter is None:
counter = [0]
index = counter[0]
counter[0] += 1

sat_class = "tree-sat" if self.satisfied else "tree-unsat"
escaped = html_module.escape(self.formula)
children_html = ""
if self.children:
items = "".join(c._build_tree_html() for c in self.children)
items = "".join(c._build_tree_html(counter) for c in self.children)
children_html = f'<ul>{items}</ul>'
return f'<li class="{sat_class}"><code>{escaped}</code>{children_html}</li>'
return f'<li class="{sat_class}" data-node-index="{index}"><code>{escaped}</code>{children_html}</li>'

def getAllSubformulae(self):
"""Extract all subformulae from this node and its children recursively."""
Expand Down Expand Up @@ -121,6 +129,31 @@ def to_dict(self):
"cycle_states": self.cycle_states
}

def getStepperViewData(self):
"""Data for the stepper view: one formula tree, one truth vector per state.

Every state evaluates the same formula, so the per-state trees are
structurally identical and differ only in which nodes are satisfied.
Sending the tree once and swapping classes per step lets the view
update in place instead of cross-fading a separate copy per state.

Vector position i corresponds to the node carrying data-node-index="i",
since getAllSubformulae and _build_tree_html walk the tree in the same
pre-order.
"""
all_states = self.prefix_states + self.cycle_states

if not all_states:
return {"tree_html": "", "steps": []}

steps = [[1 if satisfied else 0 for _, satisfied in state.getAllSubformulae()]
for state in all_states]

return {
"tree_html": all_states[0].formulaTreeAsHTML,
"steps": steps
}

def getMatrixView(self):
"""Generate matrix view data for table display."""
all_states = self.prefix_states + self.cycle_states
Expand Down
Loading
Loading