| name | plugin-runtime-debug |
| description | Use when an installed DSH Web plugin misbehaves only at runtime in the browser — paste/attachment/composer features that work once then fail, chips or panels showing stale placeholder state, update chips claiming the wrong version — and the fix must be diagnosed against the exact host API semantics rather than guessed from names. Also use when reviewing a plugin's calls into input-machine or facade verbs (insert, consume, remove, subscribe) before a release. |
Debug DSH Web Plugin Runtime Behavior
External Web plugins call host client APIs whose contracts live in the DSH
source tree, not in the plugin's own types. When behavior diverges from
intent at runtime, the failure is almost always a misread contract — and the
diagnosis must come from the host source, never from the API's name.
The standing rule: read the verb's contract in the host source first
Before changing any call into a host API, open the implementing package in
the DSH source checkout (~/.dsh/source/current, or the vendored copy) and
read the actual method — its doc comment, its guards, and the types it
compares against. Repeat for every value the plugin passes. Three questions
cover most incidents:
- Which text does an offset count into? When a verb takes a span or an
offset, find out what string those numbers index. Published snapshot
fields and internal editor projections are not always the same string; a
plugin that feeds one representation's offsets into a verb whose guard
compares against another representation fails silently — the call returns
false or no-ops, nothing throws.
- What does one "unit" weigh in each representation? If the document
contains opaque inline units (chips, tokens, attachments), check whether a
unit occupies the same width in the published field as in the projection
the verb guards. When widths differ, offsets are only correct while no
unit exists — verify what the first call succeeding and every later call
failing tells you.
- When the verb declines, who notices? A boolean-returning verb that
fails silently turns into a downstream state bug: the caller deletes its
own bookkeeping anyway, and the UI renders a "missing/unavailable"
placeholder next to an object that never went away. Audit every call site
for the "fire, ignore the result, clean up state anyway" shape.
