engine

type AttrList struct {
	Name        string // "IBusAttrList".
	Attachments map[string]dbus.Variant
	Attributes  []dbus.Variant // empty av for plain commits
}

type Component struct {
	Name          string                  // "IBusComponent".
	Attachments   map[string]dbus.Variant // {}.
	ComponentName string                  // "org.freedesktop.IBus.goswitch".
	Description   string
	Version       string
	License       string // "MIT".
	Author        string
	Homepage      string
	Exec          string // "" — programmatic registration only, never spawned.
	Textdomain    string
	ObservedPaths []dbus.Variant // empty av.
	EngineList    []dbus.Variant // MakeVariant of each EngineDesc value.
}

type Config struct {
	Component Component
	Engines   []EngineDesc
	Handler   EventHandler // may be nil — observer-only engine.

	// PostRegister is the optional self-reactivation seam (SY8): invoked
	// synchronously after EVERY successful RegisterComponent — generation 0
	// and every reconnect generation. nil = no-op. It must be cheap and
	// non-fatal: serve runs it inline before waitBusLoss, so a hang here
	// stalls the generation (the activate package's 10 s per-call timeout
	// bounds it).
	PostRegister func(ctx context.Context, generation int)

	// BindSwitcher is the optional flip seam (D-52): invoked once per
	// connection generation, right beside PostRegister, with the closure
	// that calls org.freedesktop.IBus.SetGlobalEngine on THIS generation's
	// connection. A switcher captured from a dead generation must never
	// survive the reconnect — the rebinding HERE is the guarantee
	// (T-05-03-03). nil = no-op (the PostRegister contract). The closure is
	// invoked by the actor on the flip path, never by the serve loop: a slow
	// bus can only stall a flip, never the registration cycle, and its
	// failures are journal lines (switch_engine), never generation errors.
	BindSwitcher func(flip func(ctx context.Context, engineName string) error)

	// OnGlobalEngine is the sync-listener input (05-04 criterion 3): invoked
	// with the engine name of every org.freedesktop.IBus.GlobalEngineChanged
	// signal on this connection AND of every FocusIn — the daemon follows
	// the FACTUAL active engine instead of trusting gsettings. nil = no-op.
	// It is called from the signal dispatcher's goroutine and from engine
	// D-Bus handlers: the callee must be cheap and never panic (the
	// FocusIn path is recoverHandler-wrapped). It NEVER flips anything
	// itself — the sync corrects only the receiver's internal state, never
	// the bus (single-writer, T-05-04-01).
	OnGlobalEngine func(engineName string)

	// BindGlobalEngine is the generation-scoped GetGlobalEngine reader seam
	// (05-04, Pitfall 3): invoked once per connection generation — bound
	// BEFORE PostRegister, so the same generation's reactivation can consult
	// it — with the closure that reads the FACTUAL active engine off THIS
	// generation's connection. A reader captured from a dead generation must
	// never survive the reconnect. nil = no-op (the PostRegister contract).
	BindGlobalEngine func(get func(ctx context.Context) (string, error))
}

type Emitter interface {
	RequireSurroundingText()
	DeleteSurroundingText(offset int32, nchars uint32)
	ForwardKeyEvent(keyval, keycode, state uint32)
	CommitText(text IBusText)
	UpdateModeSymbol(symbol string)
}

type Engine struct {
	// contains filtered or unexported fields
}

type EngineDesc struct {
	Name          string                  // "IBusEngineDesc".
	Attachments   map[string]dbus.Variant // {}.
	EngineName    string                  // "goswitch-en" / "goswitch-ru".
	LongName      string
	Description   string
	Language      string // "en" / "ru".
	License       string // "MIT".
	Author        string
	Icon          string
	Layout        string // "us" / "ru".
	Rank          uint32
	Hotkeys       string
	Symbol        string // "en" / "ru".
	Setup         string
	LayoutVariant string
	LayoutOption  string
	Version       string
	Textdomain    string
	IconPropKey   string // modePropKey — the dynamic panel icon property.
}

type EngineEvent struct {
	Keyval  uint32
	Keycode uint32
	Release bool
	Mods    uint32
}

type EventHandler interface {
	HandleKey(ev EngineEvent) (consume bool)
	HandleLifecycle(kind LifecycleKind)
	// HandleSurroundingText delivers the surrounding text the client
	// reported with both positions (D-30: a selection is active exactly when
	// anchorPos != cursorPos) — the input of the ADR-004 pre-correction
	// verification and of the selection-range detection.
	HandleSurroundingText(text string, cursorPos, anchorPos uint32)
	// HandleCapabilities delivers the per-input-context capability bitmap
	// (SetCapabilities), the input of the ADR-003 ladder-level choice.
	HandleCapabilities(caps uint32)
	// AttachEngine binds the emitter sink of the engine minted for the
	// input context: the handler's corrections drive it.
	AttachEngine(eng Emitter)
}

type IBusText struct {
	Name        string // "IBusText".
	Attachments map[string]dbus.Variant
	Text        string
	AttrList    dbus.Variant
}

type LifecycleKind int

type PropList struct {
	Name        string                  // "IBusPropList".
	Attachments map[string]dbus.Variant // {}.
	Properties  []dbus.Variant          // variant-wrapped Property values.
}

type Property struct {
	Name        string                  // "IBusProperty".
	Attachments map[string]dbus.Variant // {}.
	Key         string                  // modePropKey — the panel icon key.
	Type        uint32                  // PropTypeNormal (ibusproperty.h:79).
	Label       dbus.Variant            // variant-wrapped IBusText.
	Icon        string                  // "" — the symbol carries the mode.
	Tooltip     dbus.Variant            // variant-wrapped IBusText.
	Sensitive   bool
	Visible     bool
	State       uint32 // PropStateUnchecked (ibusproperty.h:109).
	SubProps    dbus.Variant
	Symbol      dbus.Variant // variant-wrapped IBusText — the panel icon glyph.
}