googlicius/obsidian-steward/interactive-widget

Interactive Widget Skill

Use this skill after the stateful-widget skill when a widget should accept model turns (play vs AI, multi-model games, turn-ordered interaction).

When to use

• User wants turn-ordered interaction with one or more model actors.
• The widget already persists state (getState / setState) — see stateful-widget first.
• You need host-dispatchable actions (registerAction) documented in Widget.md.

Skip for static widgets, user-only interactivity with no model turns, or SVG code mode.

Prerequisite workflow

1. Read stateful-widget → show_widget + working project with setState.
2. Then use this skill → registerAction in main.js (keep it last when split) + YAML fences in Widget.md.

Exposed actions (main.js)

Extract shared logic into action functions. User clicks and host dispatch call the same function. Register only actions models may invoke — not UI-only handlers (reset, local toggles).

Rules:

• fn receives params validated against the action's params spec in Widget.md.
• User event handlers should call the same function the host will dispatch.
• Do not registerAction for reset/restart — use a local button or window.stw.startNewSession() for "Play again".

File format

Path: {projectPath}/Widget.md (one per widget project under {stewardFolder}/Widgets/{widgetId}/).

• Markdown note with note-level frontmatter (status, enabled) plus ```yaml fenced blocks in the body.
• Each fence is one definition block; discriminated by the root name field.
• A host-maintained manifest YAML fence at the top of the body (see stateful-widget for schema and placement). This skill covers only actions, actors, and agent blocks you add below it.

After creating or updating Widget.md, re-read the file and check frontmatter status. If invalid, fix YAML per the error and re-read.

Note frontmatter

Host-maintained on save (do not hand-author unless missing).

YAML schema

Every fenced block you add via edit must include name as the block type identifier.

name: actions

Catalog of actions the host may dispatch. Keys must match registerAction names in main.js.

Action definition (actions.<actionName>):

Param spec (actions.<actionName>.params.<paramName>):

Only one actions block is allowed. Required when any agent block exists.

name: actors

Turn roster and policy. Required when any agent block exists.

Actor entry (actors.<actorId>):

Only one actors block is allowed. At least one kind: model actor is required when agent blocks exist.

name: agent

One fence per model actor. Repeat the block for each kind: model entry in actors.

Each agent.id must be unique across agent blocks.

Cross-validation (host-enforced)

On save, the host checks (including the host-maintained manifest block):

• At most one block each of actions, actors.
• When any agent block exists: actions and actors blocks required.
• Every agent.id has actors.<id> with kind: model.
• Every turnOrder id exists in actors.
• Every model actor in actors has an agent block.
• Every agent.actions[] name exists in actions catalog.
• No duplicate agent.id.

Fix status errors before expecting model turns to run.

How to modify Widget.md

1. content_reading on {projectPath}/Widget.md — fences + frontmatter status.
2. edit — append or update actions, actors, and agent fences below the manifest block (see stateful-widget).
3. Re-read status after save (host validates on vault modify; edit tool result may include validation when stale).

Examples

Minimal actions block (no params)

name: actions
actions:
  advanceTurn:
    description: Advance to the next phase

Tic-tac-toe

name: actions
actions:
  playCell:
    description: Place mark for current player
    params:
      index:
        type: integer
        minimum: 0
        maximum: 8

name: actors
mode: user_and_models
turnOrder:
  - user
  - o
actors:
  user:
    kind: human
  o:
    kind: model

name: agent
id: o
instruction: |
  You play O in tic-tac-toe. Pick one empty cell via playCell.
actions:
  - playCell

Matching main.js pattern:

function playCell(index) {
  // validate, update state, setState, return { ok } or { ok: false, error }
}
window.stw.registerAction('playCell', function (params) {
  return playCell(params.index);
});

Workflow

1. stateful-widget → working widget with setState.
2. registerAction + shared handlers in main.js.
3. edit Widget.md: add name: actions.
4. For model play: add name: actors + name: agent fence(s); confirm status valid.
5. Open note → widget mounts → host starts session when agents are configured.

Notes

• The editable area of Widget.md is everything below the host-maintained manifest fence — add actions, actors, and agent blocks there only (see stateful-widget for manifest rules).
• Add agent / actors only after actions works in main.js via registerAction.
• agent.actions lists a name missing from actions or not registered in main.js.
• turnOrder id not defined in actors, or agent.id mismatch.
• kind: human actor given an agent block.
• Registering UI-only actions (reset) instead of local handlers.
• Replacing entire state in setState and dropping host-owned session fields (merge instead).