mustflow 2.116.0 → 2.116.2

package/templates/default/locales/en/.mustflow/skills/input-event-synchronization-review/references/input-session-state-checklist.md

@@ -0,0 +1,298 @@
+# Input Session State Checklist
+
+Use this checklist for platform-specific input ingestion, reduction, recovery, and replay details.
+The authoritative contract remains the repository's current source and platform integration.
+
+## Contents
+
+1. [Authority and envelope](#authority-and-envelope)
+2. [Identity and order](#identity-and-order)
+3. [Loss and lifecycle recovery](#loss-and-lifecycle-recovery)
+4. [Keyboard state](#keyboard-state)
+5. [Modifier and text composition](#modifier-and-text-composition)
+6. [Immutable batches and consumers](#immutable-batches-and-consumers)
+7. [Movement and coalescing](#movement-and-coalescing)
+8. [Coordinates and mode changes](#coordinates-and-mode-changes)
+9. [Drag and capture](#drag-and-capture)
+10. [Wheel transactions](#wheel-transactions)
+11. [Diagnostics and privacy](#diagnostics-and-privacy)
+12. [Fault matrix](#fault-matrix)
+13. [Invariants](#invariants)
+14. [Skill handoffs](#skill-handoffs)
+
+## Authority and envelope
+
+Inventory each producer before changing handlers:
+
+| Producer | Authority question |
+| --- | --- |
+| native keyboard or pointer | does it own physical state or only compatibility delivery? |
+| framework event | is it synthesized from the native event already consumed elsewhere? |
+| polled gamepad or device | which poll boundary creates one observation generation? |
+| remote input | which sender epoch and sequence establish source order? |
+| replay | can it be isolated from live input and preserve recorded identity? |
+| accessibility or automation | is synthesis marked without being silently discarded? |
+
+Freeze enough evidence at the earliest controlled ingress:
+
+- source and device identity;
+- control or pointer identity;
+- source epoch and sequence;
+- stable event ID;
+- physical code and logical key or text meaning;
+- press, repeat, release, cancel, or movement kind;
+- modifier and button snapshots;
+- absolute position, relative delta, coordinate space, and transform generation;
+- native and ingress timestamps with named clock domains;
+- composition, synthesis, coalescing, warp, replay, and recovery provenance;
+- capture owner and generation when relevant.
+
+Do not defer coordinate conversion, physical-key identification, or provenance capture until mutable
+platform state has changed.
+
+## Identity and order
+
+Use `(source, epoch, sequence)` as an event identity when the source guarantees one sequence.
+Otherwise assign identity at the earliest single ingress for that source and preserve the fact that
+it is ingress order, not unknowable hardware chronology.
+
+Independent sources usually form a partial order. Do not timestamp-sort keyboard, pointer, network,
+and simulation streams into invented global causality.
+
+For each source define:
+
+- duplicate window and retention;
+- bounded reorder window;
+- behavior for an event older than the accepted window;
+- behavior for a sequence gap;
+- epoch creation and retirement;
+- snapshot or reset recovery;
+- late old-epoch rejection.
+
+Payload equality is not duplicate identity. A user can intentionally produce identical input twice.
+
+## Loss and lifecycle recovery
+
+Treat these as state-changing control events:
+
+- focus or visibility loss;
+- app deactivation, suspend, shutdown, or remote-session loss;
+- queue overrun or source reset;
+- device disconnect or generation change;
+- pointer cancel, capture loss, or pointer-lock loss;
+- input mode change that invalidates baselines.
+
+A control session ends with release or cancel. Release means the source observed a normal physical
+end. Cancel means authority was lost and the application can no longer prove the physical state.
+
+On a detected gap:
+
+1. stop applying later deltas from that source;
+2. mark the source state untrusted;
+3. obtain a current snapshot when the platform provides an authoritative one;
+4. otherwise emit ordered cancellation for active controls;
+5. start a new epoch;
+6. reject late events from the retired epoch.
+
+Never keep the previous held state while merely logging the gap.
+
+## Keyboard state
+
+Represent continuous state and transitions separately:
+
+| Current state | Event | Result |
+| --- | --- | --- |
+| up | press | down plus Press |
+| down | repeated down | down plus Repeat or Duplicate diagnostic |
+| down | release | up plus Release |
+| up | release | up plus orphan-release diagnostic |
+| down | lifecycle loss | canceled plus Cancel |
+| canceled | old-epoch event | unchanged and rejected |
+| suppressed held | release | up without synthetic command |
+| suppressed held | new press before release | platform-specific reject or reset |
+
+Use physical identity for state pairing. Logical meaning can change between press and release because
+layout and modifiers change.
+
+Define command repeat policy explicitly:
+
+- hold state reads current down state;
+- repeatable command accepts Repeat;
+- one-shot command accepts only initial Press;
+- text editing follows the platform text and composition contract.
+
+## Modifier and text composition
+
+Track left and right physical modifiers independently. Derive aggregate modifier state from the set
+of holders; never let one release clear another held modifier.
+
+Keep separate models for:
+
+- momentary modifiers held physically;
+- toggles whose logical state survives release;
+- accessibility latches that survive release until consumed;
+- event-local modifier snapshots;
+- current reducer-derived physical modifier state.
+
+Use the event-local snapshot for a shortcut tied to that event, while retaining provenance when the
+snapshot was reconstructed rather than supplied.
+
+Handle AltGraph before interpreting a Control-plus-Alt shortcut when the platform exposes AltGraph
+or an equivalent physical path.
+
+During composition, keep physical key state tracking alive but route committed text through the
+composition or input channel. Do not execute ordinary character shortcuts on intermediate
+composition data unless an explicit allowlist owns that behavior.
+
+## Immutable batches and consumers
+
+At a frame or simulation boundary:
+
+1. cut the ingress journal at one sequence boundary;
+2. reduce only that immutable slice;
+3. publish one immutable current-state snapshot and transition batch;
+4. let every consumer read the same batch through its own cursor or projection;
+5. retain or acknowledge journal entries according to the replay contract.
+
+Do not expose a destructive `wasPressed()` read that clears shared state. Do not let a mid-tick
+arrival change input already observed by earlier systems.
+
+Define slow-consumer behavior. A cursor that falls behind retention needs a resnapshot or explicit
+loss signal, not silent skipping.
+
+## Movement and coalescing
+
+Choose one compaction rule per semantic consumer:
+
+| Input use | Safe reduction candidate |
+| --- | --- |
+| relative camera | sum deltas within the tick |
+| drawing or handwriting | preserve ordered samples and pressure data |
+| hover | retain latest absolute position plus boundary transitions |
+| wheel scrolling | accumulate precision in the declared unit |
+| press, release, cancel | never coalesce or drop |
+| focus, capture, device, epoch | never coalesce or drop |
+
+When a platform exposes one representative event and its underlying coalesced samples, process one
+representation for one path. Processing both duplicates movement.
+
+Do not overwrite a frame's accumulated relative delta with the last sample.
+
+## Coordinates and mode changes
+
+Name screen, window, client, viewport, canvas, logical, device-pixel, and world spaces. Record which
+space an envelope uses and the transform generation that produced it.
+
+Compare drag anchors and current points in one coordinate space and transform generation or migrate
+both deliberately.
+
+On absolute-to-relative, relative-to-absolute, pointer-lock, DPI, viewport, zoom, or window changes:
+
+- retire invalid baselines;
+- start a new movement generation when needed;
+- mark synthetic cursor warps;
+- suppress warp-generated compatibility movement;
+- do not reinterpret old coordinates with the new transform.
+
+## Drag and capture
+
+Use an explicit gesture state machine:
+
+`Idle -> Armed -> Dragging -> Released | Clicked | Canceled`
+
+Measure the drag threshold from the original press anchor. Once click or drag is committed, do not
+oscillate between them because of later noise.
+
+Treat capture as routing ownership with `pointer + generation + owner`. Observe actual acquisition
+and loss. An old component or gesture generation cannot release a newer owner's capture.
+
+Distinguish the changed button from the current button bitmask. Use the snapshot to detect a missed
+release, but do not manufacture Press when the current gesture never admitted one.
+
+Route capture loss, target removal, pointer cancel, focus loss, and competing capture through the
+same idempotent cancel transition.
+
+## Wheel transactions
+
+Preserve horizontal and vertical deltas, fractional precision, and the declared unit. Normalize only
+at the consumer boundary with an explicit scale.
+
+Bind a burst to one owner for the platform transaction or a bounded idle interval. Re-evaluating the
+hover target after every layout change can split one physical gesture across consumers.
+
+Wheel ownership is separate from pointer capture unless the platform contract explicitly unifies
+them.
+
+## Diagnostics and privacy
+
+Keep a bounded circular journal containing:
+
+- source, device, epoch, sequence, event kind, and physical control;
+- dedupe, reorder, gap, cancellation, and rejection decisions;
+- capture owner and generation changes;
+- reducer state transitions and invariant failures;
+- batch boundary and consumer cursor lag.
+
+Avoid recording text, composed content, credentials, or sensitive application fields. Prefer
+physical identifiers, hashes where justified, counters, and lifecycle metadata.
+
+A success log emitted before reduction or batch publication is not proof that a consumer observed
+the input.
+
+## Fault matrix
+
+Cover the relevant rows:
+
+| Fault | Required observation |
+| --- | --- |
+| duplicate press | held count does not grow twice |
+| missing release | lifecycle cancel clears the session |
+| sequence gap | later deltas stop until snapshot or new epoch |
+| late old-epoch release | current state is unchanged |
+| left and right modifier overlap | releasing one preserves the other |
+| two devices hold one control | removing one preserves remaining holder |
+| repeat storm | one-shot command executes once |
+| composition plus shortcut keys | text and command paths do not double-apply |
+| raw plus synthesized movement | one physical movement applies once |
+| representative plus coalesced samples | one representation is consumed |
+| focus loss during drag | one Cancel ends capture and gesture |
+| stale capture owner release | newer capture remains owned |
+| transform change during drag | historical points are not reinterpreted |
+| mid-tick arrival | all consumers retain one batch view |
+| slow consumer beyond retention | explicit loss or resnapshot occurs |
+
+Prefer deterministic fixtures and explicit ingress gates over arbitrary sleeps. Preserve the failing
+envelope stream, epochs, batch boundaries, and invariant result for replay.
+
+## Invariants
+
+At minimum, choose applicable invariants:
+
+- every active control terminates by release or cancel;
+- one device cannot hold the same physical control more than once;
+- aggregate held state equals the non-empty holder set;
+- a retired epoch cannot mutate current state;
+- applied source sequence is monotonic within one epoch;
+- a sequence gap cannot be hidden by later delta application;
+- every frame or tick consumer sees one immutable batch;
+- one physical movement source is applied once;
+- capture has at most one current owner per pointer;
+- every drag reaches released, clicked, or canceled;
+- composition does not duplicate committed text or invoke unintended shortcuts;
+- diagnostic retention is bounded and excludes sensitive text.
+
+## Skill handoffs
+
+- Use `race-condition-review` for schedule control, happens-before, atomics, locks, and data races
+  inside ingress or reducers.
+- Use `frontend-state-ownership-review` when normalized input is correct but UI state has multiple
+  competing owners.
+- Use `state-machine-pattern` when a domain gesture or command lifecycle needs a reusable state
+  transition implementation.
+- Use `frontend-accessibility-tree-review` for keyboard parity, focus behavior, semantic
+  activation, and non-pointer alternatives.
+- Use `frame-render-performance-review` when input delay comes from long tasks, rendering, layout,
+  or main-thread scheduling rather than input-state correctness.
+- Use `input-boundary-validation-review` for hostile remote-input payload validation before
+  admitted envelopes reach this protocol.
+

package/templates/default/locales/en/.mustflow/skills/input-event-synchronization-review/references/remote-input-transport-interaction-checklist.md

@@ -0,0 +1,328 @@
+# Remote Input Transport and Interaction Checklist
+
+Use this checklist when normalized input crosses a process, host, network, injected-device, or
+rendered-frame boundary. Keep transport facts version-scoped and derive application behavior from
+the repository's semantic input contract rather than a protocol feature name.
+
+## Contents
+
+1. [Envelope and semantic delivery](#envelope-and-semantic-delivery)
+2. [Deadlines, replacement, and recovery](#deadlines-replacement-and-recovery)
+3. [Acknowledgment layers](#acknowledgment-layers)
+4. [Latency, prediction, and queue debt](#latency-prediction-and-queue-debt)
+5. [Origin lineage and loop prevention](#origin-lineage-and-loop-prevention)
+6. [Ownership and arbitration](#ownership-and-arbitration)
+7. [Reconnect and neutralization](#reconnect-and-neutralization)
+8. [Interaction context](#interaction-context)
+9. [Focus protocol](#focus-protocol)
+10. [Composition and selection](#composition-and-selection)
+11. [Clipboard protocol](#clipboard-protocol)
+12. [Surface and coordinate generations](#surface-and-coordinate-generations)
+13. [Causal diagnostics](#causal-diagnostics)
+14. [Replay and fault injection](#replay-and-fault-injection)
+15. [Invariants and repair](#invariants-and-repair)
+16. [Skill handoffs](#skill-handoffs)
+
+## Envelope and semantic delivery
+
+Preserve at least the identities and authority tokens needed by the operation:
+
+- protocol schema version;
+- session, surface, path and focus epochs;
+- source, device, pointer and press identity;
+- event, root event, parent event and apply-context identity;
+- source sequence and covered sequence range;
+- capture monotonic time and component observation time;
+- deadline and supersession key;
+- state, transform, text, composition and clipboard versions;
+- origin node, origin kind, hop path and propagation policy;
+- semantic reliability class;
+- frame identity when presentation evidence exists.
+
+Classify by meaning, not by a transport's reliable or unreliable label:
+
+| Semantic class | Preservation rule |
+| --- | --- |
+| absolute pointer or analog state | latest valid value supersedes older values |
+| relative motion or wheel | preserve the covered-range sum |
+| pen or touch path | preserve ordered shape, pressure and important turns |
+| press or release boundary | idempotent admission and explicit application acknowledgment |
+| focus, composition, clipboard or surface | ordered versioned interaction transaction |
+| state snapshot | supersedes deltas only at a declared sequence boundary |
+
+Do not place every class behind one ordered backlog. A stale high-rate movement stream must not
+block a release or interaction-closing transaction.
+
+## Deadlines, replacement, and recovery
+
+Give every continuous input an explicit usefulness deadline and supersession relation. An expired
+absolute position can be dropped when a newer position exists. An expired release cannot simply
+vanish; reconcile it against current state and promote repair when necessary.
+
+For delta ranges, carry the first and last source sequence plus the sum. Do not acknowledge a
+covered range and later apply one of its original samples again.
+
+Prefer current-state repair over replaying obsolete history:
+
+- periodically or on anomaly, send a compact held-control and interaction digest;
+- include pressed owners, modifiers, buttons, active pointers, relative accumulators, focus,
+  capture, composition, clipboard and surface versions as applicable;
+- on a gap, compare the digest at a named sequence boundary;
+- repair or open a new epoch instead of waiting for old continuous input.
+
+Reset estimators and prediction generations when the path changes. Reject late input from a retired
+path epoch even if the connection object remains alive.
+
+## Acknowledgment layers
+
+Name the layer represented by every acknowledgment:
+
+| Acknowledgment | Meaning |
+| --- | --- |
+| receive | envelope admitted through framing and validation |
+| apply | reducer accepted or idempotently replayed the semantic operation |
+| present | a named displayed frame first contains the result |
+| repair | an invariant repair closed the discrepancy |
+
+Transport delivery evidence is not application acceptance. Stop redundant boundary-event carriage
+only after the intended application layer confirms the stable event identity.
+
+Link an apply acknowledgment to state version or state digest. Link present acknowledgment to a
+render, encode, decode and presentation frame chain when the product claims visible latency.
+
+## Latency, prediction, and queue debt
+
+Use local prediction only for reversible presentation such as cursor position, drag outline, ink
+preview, hover or press animation. Never feed predicted samples back into the authoritative input
+journal or use them to commit irreversible commands.
+
+Invalidate a prediction when the next authoritative sample or generation arrives. Reconcile the
+presentation layer without creating another input event.
+
+Limit queues by time debt: oldest still-useful event age, deadline miss, reorder depth and render
+queue depth. Under pressure:
+
+- discard superseded absolute samples first;
+- fold relative ranges without losing their sum;
+- simplify paths while preserving semantic turns;
+- retain boundary and interaction transactions;
+- isolate clipboard bodies, diagnostics and bulk data from latency-sensitive input flow.
+
+Measure capture-to-present tail latency by named stages. Average network delay alone cannot prove
+input responsiveness.
+
+## Origin lineage and loop prevention
+
+Preserve origin and causal lineage across normalization, serialization, injection, application,
+derived command and rendered feedback. Transforming an event does not create a new root user action.
+
+Separate local capture from remote application:
+
+- capture path produces outbound user intent;
+- inbound path validates and reduces a remote command;
+- effect execution does not automatically produce a new outbound user intent;
+- derived semantic or compatibility events inherit root identity and a non-propagating policy unless
+  an explicit rule permits another hop.
+
+Prefer a dedicated injected device or exact platform marker and session token. Do not suppress
+similar local input for a guessed time interval.
+
+Replace a global `isApplyingRemote` boolean with an apply-context token propagated through async
+continuations and task queues.
+
+Stop propagation when the current node already appears in the path, the policy forbids forwarding,
+or a bounded hop limit is exceeded. Record the rejection reason.
+
+## Ownership and arbitration
+
+Track held state by source owner and press identity. Aggregate physical state is the union of current
+owners, not one shared boolean and not an opaque reference count.
+
+Choose conflict policy per resource:
+
+| Resource | Typical authority shape |
+| --- | --- |
+| independent modifier holders | owner-set union |
+| text composition | one exclusive authority and generation |
+| drag or pointer capture | one owner lease with fencing generation |
+| absolute cursor | explicit local-first or current-controller policy |
+| clipboard | version, origin and content-policy arbitration |
+| surface control | one admitted controller for one surface epoch |
+
+Local takeover increments the generation, cancels displaced ownership and rejects subsequent stale
+owner input. Expiry alone is insufficient when an old owner can resume; the reducer must check the
+generation.
+
+## Reconnect and neutralization
+
+Before admitting a new session or surface epoch:
+
+1. pause new state-changing input;
+2. cancel or reconcile old held controls, pointer capture, drag and composition;
+3. retire old session, path, focus and surface generations;
+4. exchange current state and interaction-context digests;
+5. confirm neutral or explicitly transferred ownership;
+6. confirm coordinate and target generations;
+7. admit new-epoch input.
+
+Reject late old-epoch releases, movement and composition updates. A new connection does not erase
+the old connection's semantic tail.
+
+## Interaction context
+
+Keep one versioned snapshot containing applicable fields:
+
+- operating-system activation;
+- document visibility;
+- active remote surface;
+- focused logical target and focus generation;
+- selection and text revision;
+- composition ID, revision, range and status;
+- clipboard version, origin and content metadata;
+- viewport and transform generation;
+- held-state and capture digest.
+
+A command carries the context versions it assumes. Reject or reconcile it when those assumptions no
+longer hold.
+
+Do not collapse activation, visibility, surface selection and editing focus into one boolean.
+
+## Focus protocol
+
+Model focus as request, apply and confirmation:
+
+1. sender requests a stable logical target and expected focus or surface generation;
+2. authority validates target existence, ownership and policy;
+3. authority applies actual focus or chooses an explicit safe fallback;
+4. authority returns the new generation and actual target;
+5. dependent composition or shortcut work starts only from that confirmed generation.
+
+Coordinates and transient object paths are not stable target identity. A destroyed target must not
+receive a late focus confirmation.
+
+## Composition and selection
+
+Choose one composition authority per editing session:
+
+- local-authority mode sends versioned composition or text-edit operations, not both those results
+  and the physical keys that would reproduce them remotely;
+- remote-authority mode sends admitted physical or language-switch intent and does not resend local
+  composition output.
+
+Version composition with ID, revision, base text revision, target range, data classification and
+open, committed or canceled status. Commit and cancel close it exactly once. Reject updates for a
+closed composition or stale base text revision.
+
+Close or transfer composition through a barrier before focus or surface changes.
+
+Define one protocol text-index unit and convert at adapters. Do not exchange an unqualified numeric
+selection range across runtimes that count text differently.
+
+## Clipboard protocol
+
+Treat clipboard state as a versioned multi-representation object:
+
+- origin and change identity;
+- content hash or equivalent stable identity;
+- available representation types and sizes;
+- sensitivity and automatic-transfer policy;
+- expiry and user-approval requirements.
+
+First advertise metadata. Transfer only a requested representation over a bounded lower-priority
+path. Keep large images, files and rich data away from the input latency queue.
+
+Reject an echo when a locally observed change is the version just written from remote. Synthetic
+events alone are not proof that the system clipboard or target document changed.
+
+Do not log or automatically synchronize secret fields, locked-session content, or disallowed
+applications.
+
+## Surface and coordinate generations
+
+Treat a surface switch as an input barrier:
+
+1. pause state-changing input;
+2. close or cancel drag, capture, held buttons and composition;
+3. increment the surface epoch;
+4. publish size, scale, rotation, safe area and transform generation;
+5. confirm target focus and first applicable frame;
+6. resume input for the new epoch.
+
+Carry transform generation on every coordinate-bearing event. Reject, reproject deliberately, or
+request a new sample when it does not match current authority.
+
+Split absolute baselines and relative accumulators across surface epochs.
+
+## Causal diagnostics
+
+Record the lifecycle stages relevant to the architecture:
+
+`captured -> normalized -> queued -> serialized -> sent -> received -> validated -> deduplicated -> applied -> rendered -> presented -> acknowledged`
+
+Also record `dropped` and `repaired` as decisions with machine-readable reason codes.
+
+Preserve event, root, parent, trace, source, epoch, sequence, frame, thread or executor, queue age,
+context versions and state hashes. Record state hash before and after reducer application and the
+rule version that made the decision.
+
+Keep source occurrence time and component observation time separate. Build order from source
+sequence, process order and send/receive parent relationships. Clock offset estimates are latency
+evidence with uncertainty, not causality.
+
+Use a bounded low-overhead ring for high-rate data. Summarize paths and delta ranges; never sample
+away boundary, generation, capture or invariant events. Redact text and clipboard content by
+default.
+
+## Replay and fault injection
+
+Replay normalized envelopes against the production reducer with:
+
+- a virtual monotonic clock;
+- recorded receive order and causal parent links;
+- path, session, surface and interaction epochs;
+- network and application pause script;
+- deterministic random seed;
+- expected decision and state hash.
+
+Inject burst delay, jitter, consecutive loss, reordering, duplication, path change, acknowledgment
+delay, process or main-thread pause, hidden or suspend, reconnect, surface switch, capture theft,
+composition focus loss and clipboard transfer pressure.
+
+Compare a healthy and failing run by root event and find the first state-hash divergence rather than
+the final visible symptom.
+
+A reproducible bundle should version its schema and include build, feature flags, platform, layout,
+scale, network fault plan, bounded event ring, state snapshots and seed. Keep sensitive content
+redacted unless explicitly authorized.
+
+## Invariants and repair
+
+Choose applicable executable invariants:
+
+- one stable event changes reducer state at most once;
+- no old session, path, surface, focus, lease or composition generation changes current authority;
+- every admitted press owner terminates by release, cancel or repair;
+- one exclusive drag, capture or composition owner exists;
+- apply acknowledgments match the recorded state version or digest;
+- a closed composition cannot advance;
+- clipboard echo does not create a new root action;
+- an inbound applied effect cannot silently become outbound user intent;
+- input applied to a frame uses the admitted surface and transform generation;
+- queue debt cannot hide boundary events behind obsolete continuous input.
+
+A watchdog creates an explicit non-propagating repair event with cause, prior state hash, action and
+result. Repair is not fabricated user input.
+
+## Skill handoffs
+
+- Use `input-boundary-validation-review` for authentication, size, schema and hostile remote
+  envelope validation.
+- Use `performance-measurement-integrity-review` for latency units, clock domains, tail metrics and
+  benchmark comparability.
+- Use `adapter-boundary` for platform injection, capture and transport adapter isolation.
+- Use `race-condition-review` for shared-memory interleavings inside capture, transport or reducer
+  code.
+- Use `two-phase-transition-integrity-review` when controller or surface handoff has durable
+  admission and commit phases.
+- Use `provenance-license-gate` before copying external protocol text, schemas or example code.
+