* refactor: align widget actions with scene pipeline * feat(edit): migrate legacy teacherActions off interactive content on load The widget-actions pipeline no longer persists a teacherActions authoring layer; playback reads only scene.actions. Add migrateInteractiveContent to strip the dead field from existing documents as they load through migrateScene (wired into all store/classroom load paths). Satisfies the #794 forward-migration acceptance item. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(generation): default widget_setState.state to {} when the LLM omits it The removed TeacherAction->Action converter always defaulted state to {}. Restore that guard in the structured-output parser so an action missing state can't forward state: undefined into the widget iframe, where SET_WIDGET_STATE handlers dereference it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(edit): also strip nested widgetConfig.teacherActions in migration Legacy WidgetConfig variants each declared their own teacherActions, so existing documents can carry the dead field nested inside content.widgetConfig as well as at the top level. Extend migrateInteractiveContent to drop both, preserving all other widgetConfig fields. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(prompts): document stable widget-action selectors for diagram/game/viz3d The interactive-actions prompt documented stable target selectors only for procedural-skill and simulation widgets. Add the canonical selectors the diagram / game / visualization3d content prompts actually emit (node IDs via revealOrder; #zoom-in-btn / #canvas-container / #speed-slider / ...; #start-btn), plus a rule to use widget_setState or a speech-only beat instead of guessing a target when no stable selector is known (e.g. free-form code widgets). Hardens against widget actions silently no-oping on non-existent selectors. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
lib/prompts
File-based prompt loader + templates shared by both the generation pipeline and the runtime orchestration layer.
Directory layout
lib/prompts/
├── loader.ts ← file I/O + cache
├── index.ts ← public API (loadPrompt, buildPrompt, …) + PROMPT_IDS
├── types.ts ← PromptId / SnippetId string literal unions
├── templates/
│ └── <prompt-id>/
│ ├── system.md ← required
│ └── user.md ← optional (mostly for offline generation prompts)
└── snippets/
└── <snippet-id>.md ← reusable blocks referenced via {{snippet:…}}
Template syntax
Three kinds of placeholder:
| Syntax | Semantics | Resolved by |
|---|---|---|
{{variableName}} |
Value is provided by the caller via buildPrompt(id, vars) |
interpolateVariables in loader.ts |
{{snippet:snippet-name}} |
File content is spliced in at load time | processSnippets in loader.ts |
{{#if conditionName}}...{{/if}} |
Content is included only when conditionName is truthy in the template variables |
processConditionalBlocks in loader.ts |
Processing order is snippet includes first, then conditional blocks, then
variable interpolation, so snippets may themselves contain {{#if}}
blocks and {{variableName}} placeholders if the caller provides the value.
Conditional blocks read from the same variables record passed to
buildPrompt — no separate conditions object is needed.
Naming conventions
- Placeholder names use
camelCase. Example:{{agentName}},{{stateContext}}. - Template IDs use
kebab-case. Example:agent-system,pbl-design. lib/prompts/templates/slide-content/{system,user}.mdstill uses legacysnake_caseplaceholders ({{canvas_width}},{{canvas_height}}). This predates the camelCase convention; don't imitate it when writing new templates.
Adding a new prompt
- Create
lib/prompts/templates/<new-id>/system.md(anduser.mdif needed). - Add
<new-id>to thePromptIdunion intypes.ts. - Add
NEW_ID: '<new-id>'to thePROMPT_IDSconstant inindex.ts(thesatisfies Record<string, PromptId>clause enforces that the value exists in the union). - Call
buildPrompt(PROMPT_IDS.NEW_ID, vars)from the consuming module.
Still in TypeScript (not yet in templates)
Not every prompt fragment lives in markdown. Some role-conditional content still exists as TS template literals and needs editing directly:
| What | Where | Why not in markdown |
|---|---|---|
ROLE_GUIDELINES (teacher / assistant / student blocks) |
lib/orchestration/prompt-builder.ts |
Branches by agentConfig.role |
| Length targets (100 / 80 / 50 chars per role) | buildLengthGuidelines in lib/orchestration/prompt-builder.ts |
Branches by role |
These may migrate into snippets in a later pass once Phase 2 eval feedback shows which parts need frequent iteration.
Silent-passthrough gotcha
interpolateVariables leaves unknown placeholders unchanged rather than
throwing:
interpolate('hello {{missing}}', {}) === 'hello {{missing}}'
This is intentional for partial-render scenarios but means a typo in a
placeholder name ships literal {{…}} text to the LLM. Defence:
- Tests in
tests/prompts/templates.test.tsassert that the fully-rendered agent-system / director / pbl-design prompts contain no surviving{{…}}tokens. Keep that check passing when adding variables. {{snippet:name}}lookups throw on a missing snippet file rather than passing through silently, so a typo like{{snippet:speach-guidelines}}fails at load time instead of reaching the LLM.
Testing a template change locally
The cheapest feedback loop is the template smoke suite:
pnpm test tests/prompts
For end-to-end runtime behaviour (agent loop + template composition + chat/director integration), use the whiteboard eval harness on one scenario:
PORT=3100 pnpm dev &
EVAL_CHAT_MODEL=<provider:model> EVAL_SCORER_MODEL=<provider:model> \
pnpm eval:whiteboard --base-url http://localhost:3100 \
--scenario econ-tech-innovation
Loading
loadPrompt and loadSnippet read from disk on every call. No caching —
markdown edits take effect immediately without restarting any dev server.
Prompt disk I/O is negligible next to the LLM call it feeds.