@hydraharness/harness-client-ui-input-trigger 0.0.0-stage → 0.1.1-rc.7

package/lib/index.js

@@ -0,0 +1,11 @@
+//#region lib/types/index.js
+/**
+* Slash trigger plugin, node half. Pure UI plugin: the empty apply exists so
+* the plugin appears in the host cordis.yml / Loader; the browser half ships
+* via exports["./client"], discovered through the package.json hydra.client
+* declaration.
+*/
+/** Host plugin body — no host-side behavior for the slash trigger plugin. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-client-ui-input-trigger`.
+* @module @hydraharness/harness-client-ui-input-trigger/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-client-ui-input-trigger";
+/** Cordis companion plugin name. */
+const name = "client-ui-input-trigger-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the trigger pipeline is a browser-side pure core
+* (detect/reduce/match) plus a registry whose disposal is proven by the
+* HMR-safety spec; it emits no cordis events and owns no cross-plugin
+* mutable state.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client/MenuView.d.ts

@@ -0,0 +1,11 @@
+import type { PropsLocale } from '@hydraharness/harness-client-ui-slots';
+import type { MenuViewInjected } from './slots.ts';
+/** Full menu props: injected face + the locale seat. */
+export type MenuViewProps = MenuViewInjected & PropsLocale<'slash.menu'>;
+/**
+ * Render the candidate menu overlay entry.
+ * @param props - injected face (the menu store and the pick route); `t` rides the standard locale seat.
+ * @returns the dropdown while open; null while closed.
+ */
+export declare function MenuView({ menu, onPick, onDismiss, t }: MenuViewProps): import("react").JSX.Element | null;
+//# sourceMappingURL=MenuView.d.ts.map

package/lib/types/client/contract.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Frozen service contract of the slash pipeline. Types only. The
+ * InputTriggerService implementation publishes this face as `ctx.inputTriggers`; sources
+ * see registerSource alone, the conversation wiring layer resolves its
+ * per-session controller through sessionOf.
+ */
+import type { ClientContext } from '@hydraharness/harness-client-runtime/client';
+import type { InputTriggerSource } from '../types.ts';
+import type { InputTriggerController } from './controller.ts';
+/** The `ctx.inputTriggers` service face. */
+export interface InputTriggerServiceContract {
+    /**
+     * Register one trigger source; duplicate trigger/name pairs throw.
+     * @param src - source that discovers and resolves slash or reference candidates.
+     * @returns effect disposer removing this source.
+     */
+    registerSource(src: InputTriggerSource): () => void;
+    /**
+     * Resolve the lazy controller owned by one session scope.
+     * @param actx - session-scoped Client context.
+     * @returns controller that dies with that scope.
+     */
+    sessionOf(actx: ClientContext): InputTriggerController;
+}
+//# sourceMappingURL=contract.d.ts.map

package/lib/types/client/controller.d.ts

@@ -0,0 +1,153 @@
+/**
+ * InputTriggerController: the per-session half of the trigger pipeline. Owns every
+ * piece of mutable interaction state — the authoritative trigger hit (span
+ * included; it outlives menu close for space adjudication), the menu store,
+ * and the candidate-fetch lifecycle — and executes pick outcomes by
+ * dispatching the scoped input-mutation events. The root InputTriggerService keeps
+ * only the source roster. One controller per session scope; the service
+ * disposes it with the scope fiber.
+ */
+import type { ClientContext, SessionId, SnapshotStore } from '@hydraharness/harness-client-runtime/client';
+import type { MenuState, TriggerHit } from '../core/contract.ts';
+import type { ArbitrateKey, ArbitrateOutcome, PickOutcome, InputTriggerSource, SubmitEnvelope, TriggerChar, TriggerGuard } from '../types.ts';
+/** Roster access the controller borrows from the root service (registration order preserved). */
+export interface SourceRoster {
+    sources(trigger: string): readonly InputTriggerSource[];
+    all(): readonly InputTriggerSource[];
+}
+/** Construction hooks for one controller. */
+export interface InputTriggerControllerDeps {
+    /** The owning session scope (event dispatch + teardown registration site). */
+    actx: ClientContext;
+    /** The session's stable host identity (the projection handed to sources). */
+    sessionId: SessionId;
+    /** Root-service roster view. */
+    roster: SourceRoster;
+}
+/**
+ * Per-session trigger pipeline state and orchestration. All mutation stays
+ * inside; MenuView renders from {@link InputTriggerController.menu} and routes
+ * pointer picks back through {@link InputTriggerController.pick}.
+ */
+export declare class InputTriggerController {
+    private readonly deps;
+    /** Menu state store (per-session; survives session switches, dies with the scope). */
+    readonly menu: SnapshotStore<MenuState>;
+    /**
+     * Name of the source opened through the programmatic launcher, or null for
+     * trigger-detected/closed menus. Composer chrome subscribes to this store
+     * for the launcher's expanded state without owning a second menu model.
+     */
+    readonly launcher: SnapshotStore<string | null>;
+    /**
+     * Aggregated hot reference lexicon, grouped by trigger (plain-text-reference decision;
+     * see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md):
+     * sources implementing the lexicon hook are polled with the session
+     * projection; undefined answers (roll not hot yet) are skipped; multiple
+     * sources on one trigger concatenate in registration order. A snapshot
+     * store because rolls change asynchronously (catalog settles, children
+     * spawn/exit) — render-side consumers subscribe instead of re-reading a
+     * mutable answer.
+     */
+    readonly lexicon: SnapshotStore<ReadonlyMap<TriggerChar, readonly string[]>>;
+    /** The authoritative hit: single truth for span CAS material (menu snapshot never carries it alone). */
+    private hit;
+    private fetch;
+    private disposed;
+    /** Per-source lexicon unsubscribers (sources without the hook never enter). */
+    private readonly lexiconOffs;
+    constructor(deps: InputTriggerControllerDeps);
+    /**
+     * Feed a draft/caret change through trigger detection and drive the menu.
+     * @param draft - full draft text.
+     * @param caret - caret offset into `draft`.
+     * @param guard - availability tier derived from the input phase.
+     * @param draftRev - the input machine's current draft revision, stamped
+     * into the hit span for pick-time CAS.
+     */
+    track(draft: string, caret: number, guard: TriggerGuard, draftRev: number): void;
+    /**
+     * Toggle a menu containing exactly one registered source. The supplied hit
+     * is a synthetic selection span rather than a typed trigger token, but
+     * picks deliberately reuse the ordinary source callback and scoped input
+     * mutation pipeline.
+     * @param source - registered source name under `hit.trigger`.
+     * @param hit - synthetic hit carrying position and pick-time draft CAS.
+     */
+    toggleSource(source: string, hit: TriggerHit): void;
+    /**
+     * Pointer pick from MenuView: route the clicked candidate through onPick
+     * and execute claim/insert outcomes via the scoped input events.
+     * @param source - source (group) name.
+     * @param index - candidate index within the group.
+     */
+    pick(source: string, index: number): void;
+    /**
+     * Keyboard arbitration while the menu is open.
+     * @param key - intercepted key.
+     * @param composing - inside IME composition: everything passes.
+     * @returns consumed / pick-highlighted / pass.
+     */
+    arbitrate(key: ArbitrateKey, composing: boolean): ArbitrateOutcome;
+    /**
+     * Space adjudication over the just-completed leading token: polls sources'
+     * matchSpace (hot state, synchronous) and dispatches the outcome itself.
+     * @returns true when a claim/insert was actually applied by the input —
+     * the caller preventDefaults exactly then.
+     */
+    onSpace(): boolean;
+    /**
+     * Serialize one reference occurrence to its model form via the owning
+     * source's codec (prompt serialization: registry → explicit
+     * call → await). Owner missing or codec-less rejects — the submit attempt
+     * blocks instead of silently downgrading to the clipboard text.
+     * @param source - owning source name.
+     * @param ref - owner-scoped reference id.
+     * @param signal - the submit attempt's abort signal.
+     * @returns the model representation (e.g. `<skill>name</skill>`).
+     */
+    serializeReference(source: string, ref: string, signal: AbortSignal): Promise<string>;
+    /**
+     * Enter last adjudication: polls sources' matchEnter in registration
+     * order, first non-undefined wins. The outcome returns to the caller (the
+     * input machine applies it inside the same submit attempt — no event).
+     * @param line - trimmed draft; the leading char selects the trigger roster.
+     * @param signal - attempt-scoped abort from the input machine.
+     * @param envelope - non-text submission state accompanying the draft.
+     * @returns the winning outcome or undefined (default sink). Rejects when a
+     * polled source's warmup fails or the winning source refuses the envelope —
+     * the caller must not silently downgrade.
+     */
+    adjudicate(line: string, signal: AbortSignal, envelope: SubmitEnvelope): Promise<PickOutcome>;
+    /**
+     * Drop the menu group of a disposed source (root registry change notification).
+     * @param source - the source whose registration was disposed.
+     */
+    sourceRemoved(source: InputTriggerSource): void;
+    /**
+     * Admit a source registered after this controller's birth (root registry
+     * change notification): warm it and fold its roll into the live lexicon —
+     * the constructor-time prewarm covers only the roster present at scope
+     * birth.
+     * @param source - the newly registered source.
+     */
+    sourceAdded(source: InputTriggerSource): void;
+    /** External dismiss (e.g. pointer outside the composer area). */
+    dismiss(): void;
+    /** Scope teardown: close and abort (the service deletes the map entry). */
+    dispose(): void;
+    /** The session projection handed to sources (agent-backed identity; constant per scope). */
+    private project;
+    /** Execute a claim/insert/text outcome via the scoped input events (actx as dispatch subject); true = the input applied it. */
+    private execute;
+    /** Re-poll every lexicon-bearing source and publish the aggregated rolls (see the store doc). */
+    private refreshLexicon;
+    /** Wire one source's lexicon invalidation channel into refresh (hookless or roll-less sources never notify). */
+    private watchLexicon;
+    /** Launch the candidate fetch for one hit generation, superseding the previous one. */
+    private fetchCandidates;
+    private stopFetch;
+    private clearLauncher;
+    private reduce;
+}
+//# sourceMappingURL=controller.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,32 @@
+import type { ClientContext } from '@hydraharness/harness-client-runtime/client';
+import { type MenuKey } from './locales.ts';
+export { InputTriggerService } from './service.ts';
+export { InputTriggerController } from './controller.ts';
+export type { InputTriggerControllerDeps, SourceRoster } from './controller.ts';
+export type { MenuViewInjected } from './slots.ts';
+export type { MenuViewProps } from './MenuView.tsx';
+export type { MenuKey } from './locales.ts';
+export type { ArbitrateKey, ArbitrateOutcome, BeginCommandRequest, CandidateRequest, ClientSessionContext, CommandClaim, ConsumeTokenRequest, InsertReferenceRequest, PickOutcome, PickVia, ReferenceCodec, ReferenceInsert, InputTriggerCandidate, InputTriggerPick, InputTriggerSource, SubmitEnvelope, SubmitImageAttachment, SubmitOutcome, TokenSpan, TriggerChar, TriggerGuard, TriggerPosition, } from '../types.ts';
+export type { DetectTrigger, ExactMatch, MenuEvent, MenuReduce, MenuState, TriggerHit } from '../core/contract.ts';
+export type { InputTriggerServiceContract } from './contract.ts';
+declare module '@hydraharness/cordis' {
+    interface Context {
+        /** The outward face only; the concrete service stays inside this plugin. */
+        inputTriggers: import('./contract.ts').InputTriggerServiceContract;
+    }
+}
+declare module '@hydraharness/harness-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The candidate menu's copy: group titles keyed by source name, the pending row, and the listbox aria. */
+        'slash.menu': MenuKey;
+    }
+}
+/** Required services: controller resolution reads the session scope tree; the menu copy is localized. */
+export declare const inject: string[];
+/**
+ * Client plugin body: mount the service, then register MenuView into the
+ * input overlay once its declarer is up.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `slash.menu` namespace dictionaries: group titles keyed by source name
+ * (the lookup chain returns the key itself, so an unknown source shows its
+ * raw name), the pending row, and the listbox aria label.
+ */
+/** English dictionary (the key-set source of truth). */
+export declare const en: {
+    command: string;
+    skill: string;
+    subagent: string;
+    loading: string;
+    'suggestions.aria': string;
+};
+/** The slash.menu namespace key union. */
+export type MenuKey = keyof typeof en;
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/service.d.ts

@@ -0,0 +1,41 @@
+/**
+ * InputTriggerService (`ctx.inputTriggers`): the root half of the trigger pipeline — the
+ * stateless source registry plus the per-session controller map. Every piece
+ * of mutable interaction state (hit, menu, fetch) lives on the
+ * {@link InputTriggerController}; the service only registers sources, resolves
+ * controllers by session scope, and relays roster changes.
+ */
+import { Service } from '@hydraharness/cordis';
+import type { Context } from '@hydraharness/cordis';
+import type { ClientContext } from '@hydraharness/harness-client-runtime/client';
+import type { InputTriggerSource } from '../types.ts';
+import { InputTriggerController } from './controller.ts';
+import type { InputTriggerServiceContract } from './contract.ts';
+/** The `ctx.inputTriggers` trigger pipeline service (root registry + controller resolution). */
+export declare class InputTriggerService extends Service implements InputTriggerServiceContract {
+    static inject: string[];
+    private readonly live;
+    /**
+     * @param ctx - owning root context (the service registers itself as `slash`).
+     */
+    constructor(ctx: Context);
+    /**
+     * Register one trigger source. Live session controllers are notified so a
+     * source arriving after scope birth still warms and joins the lexicon.
+     * @param src - the source; (trigger, name) must be unique — duplicates throw.
+     * @returns the disposer (callers wrap registration in ctx.effect). Disposal
+     * while a controller shows the source's menu group drops that group.
+     */
+    registerSource(src: InputTriggerSource): () => void;
+    /**
+     * Resolve the per-session controller for one session scope (lazy; the
+     * scope disposer removes and disposes it). Construction warms the source
+     * roster once — sessions are always agent-backed, so scope birth is the
+     * single prewarm moment.
+     * @param actx - session-scope ctx.
+     * @returns the resident controller.
+     */
+    sessionOf(actx: ClientContext): InputTriggerController;
+    private sessions;
+}
+//# sourceMappingURL=service.d.ts.map

package/lib/types/client/slots.d.ts

@@ -0,0 +1,31 @@
+import type { SnapshotStore } from '@hydraharness/harness-client-runtime/client';
+import type { MenuState } from '../core/contract.ts';
+declare module '@hydraharness/harness-client-ui-slots' {
+    interface SlotMap {
+        /**
+         * The InputBar floating overlay anchor: MenuView (this package) and the
+         * popupSelect shell (ui-commands) contribute list entries; each reads its
+         * own store and renders null while closed. Declared (children table) by
+         * ui-conversation's composer entry; the anchor hides with the input
+         * under a takeover.
+         */
+        'conversation.input.overlay': {
+            kind: 'list';
+            scope: 'session';
+        };
+    }
+}
+/** Injected business face of the MenuView overlay entry (copy rides the standard locale seat, not this face). */
+export interface MenuViewInjected {
+    /** The service's menu state store (read-only here; MenuView subscribes). */
+    menu: SnapshotStore<MenuState>;
+    /**
+     * Pointer pick routed back through the service pipeline.
+     * @param source - source (group) name.
+     * @param index - candidate index within the group.
+     */
+    onPick: (source: string, index: number) => void;
+    /** Dismiss the menu (external pointer outside the composer area). */
+    onDismiss: () => void;
+}
+//# sourceMappingURL=slots.d.ts.map

package/lib/types/core/contract.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Frozen pure-core contract: trigger detection and
+ * menu reduction, zero React / DOM / cordis. Types only — implementations
+ * live in sibling modules annotated with these
+ * aliases; the service shell wires them to ctx.
+ */
+import type { InputTriggerCandidate, TokenSpan, TriggerChar, TriggerGuard, TriggerPosition } from '../types.ts';
+/** A detected trigger token under the caret. */
+export interface TriggerHit {
+    readonly trigger: TriggerChar;
+    /** Text between the trigger char and the caret, live-filtered. */
+    readonly query: string;
+    /** True only for an open quoted `@file` token. */
+    readonly quoted: boolean;
+    /** leading = draft trimmed (whitespace incl. newlines) starts with the token. */
+    readonly position: TriggerPosition;
+    /** Token span; draftRev injected by the caller. */
+    readonly span: TokenSpan;
+}
+/**
+ * Detect a trigger token at the caret under the given guard tier.
+ * `@` uses the shared file-reference start/whitespace grammar; `/` accepts
+ * punctuation boundaries with URL carve-outs. `user@host` and URL `/` do not
+ * trigger.
+ * Returns null when no trigger is live at the caret.
+ */
+export type DetectTrigger = (draft: string, caret: number, guard: TriggerGuard) => TriggerHit | null;
+/** Menu state: one group per source; empty ready groups auto-close the menu. */
+export interface MenuState {
+    readonly open: boolean;
+    readonly hit: TriggerHit | null;
+    /** Monotonic per-hit generation; stale source settlements are dropped. */
+    readonly generation: number;
+    readonly groups: readonly {
+        readonly source: string;
+        /** False when candidate section rows own all visible group labeling. */
+        readonly showGroupTitle?: boolean;
+        readonly status: 'pending' | 'ready';
+        readonly items: readonly InputTriggerCandidate[];
+    }[];
+    readonly highlight: {
+        readonly source: string;
+        readonly index: number;
+    } | null;
+}
+/** Menu reduction events. Source failure = silent group removal (log only; no error UI tier). */
+export type MenuEvent = {
+    readonly type: 'hit';
+    readonly hit: TriggerHit | null;
+} | {
+    readonly type: 'source-settled';
+    readonly generation: number;
+    readonly source: string;
+    readonly items?: readonly InputTriggerCandidate[];
+} | {
+    readonly type: 'source-failed';
+    readonly generation: number;
+    readonly source: string;
+} | {
+    readonly type: 'move';
+    readonly dir: 1 | -1;
+} | {
+    readonly type: 'close';
+};
+/** Pure menu reducer; returns the same reference when the event is stale or a no-op. */
+export type MenuReduce = (state: MenuState, ev: MenuEvent) => MenuState;
+/**
+ * Exact-name lookup in one source's ready group; null when absent or the
+ * group is not ready.
+ */
+export type ExactMatch = (groups: MenuState['groups'], source: string, name: string) => InputTriggerCandidate | null;
+//# sourceMappingURL=contract.d.ts.map

package/lib/types/core/detect.d.ts

@@ -0,0 +1,19 @@
+import type { DetectTrigger } from './contract.ts';
+/**
+ * Detect a trigger token at the caret. `@` first uses the shared grammar,
+ * including an open quoted token that may span whitespace. Slash detection
+ * scans left to the first whitespace; slashes failing the word boundary are
+ * treated as ordinary token chars and the scan continues (URL slashes).
+ * Guard tiers: plain = both chars live; claimed = '/' fully suppressed,
+ * '@' live; frozen = none.
+ *
+ * @param draft - Full draft text.
+ * @param caret - Caret offset into `draft`.
+ * @param guard - Availability tier derived from the input phase.
+ * @returns The hit with `query` = trigger-to-caret slice and `span` =
+ * `{start: triggerIndex, end: caret}`; `span.draftRev` is a placeholder `0`
+ * — the calling shell stamps the real revision. Null when no trigger is
+ * live at the caret.
+ */
+export declare const detectTrigger: DetectTrigger;
+//# sourceMappingURL=detect.d.ts.map

package/lib/types/core/menu.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Menu reduction pure core. One group per source;
+ * generation-gated settlement; empty ready groups auto-close. Zero React /
+ * DOM / cordis. Stale or no-op events return the same state reference so
+ * store subscribers skip re-renders.
+ *
+ * Roster protocol: the frozen `hit` event carries no source roster, so the
+ * reducer cannot invent groups. Opening from a closed state, the shell seeds
+ * the roster with {@link seedGroups} and then dispatches `hit`; a `hit`
+ * while open (query refinement) resets the existing groups to pending under
+ * a new generation. Auto-close and explicit close drop the groups.
+ */
+import type { InputTriggerSource } from '../types.ts';
+import type { ExactMatch, MenuReduce, MenuState } from './contract.ts';
+/** Closed rest state with generation 0; store initializer and test seed. */
+export declare const MENU_CLOSED: MenuState;
+/**
+ * Replace the group roster with pending groups for `sources`, in order.
+ * Shell-side step before dispatching `hit` on a fresh menu open.
+ *
+ * @param state - Current menu state.
+ * @param sources - Sources registered for the hit trigger, in menu order.
+ * @returns State carrying the new pending roster; highlight cleared.
+ */
+export declare function seedGroups(state: MenuState, sources: readonly Pick<InputTriggerSource, 'name' | 'showGroupTitle'>[]): MenuState;
+/**
+ * Pure menu reducer. `hit` opens a new generation over the seeded roster
+ * (null hit closes); `source-settled` outside the current generation, the
+ * open menu, or the roster is dropped; a settlement or failure leaving every
+ * group ready-and-empty (or no groups) auto-closes; `source-failed` silently
+ * removes the group (the shell logs); `move` cycles the highlight across
+ * ready items.
+ *
+ * @param state - Current menu state.
+ * @param ev - Menu event.
+ * @returns Next state; the same reference when stale or a no-op.
+ */
+export declare const menuReduce: MenuReduce;
+/**
+ * Exact-name lookup in one source's ready group.
+ *
+ * @param groups - Menu groups.
+ * @param source - Source (group) name.
+ * @param name - Candidate name to match exactly.
+ * @returns The candidate, or null when the group is absent, not ready, or
+ * has no candidate of that name.
+ */
+export declare const exactMatch: ExactMatch;
+//# sourceMappingURL=menu.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Slash trigger plugin, node half. Pure UI plugin: the empty apply exists so
+ * the plugin appears in the host cordis.yml / Loader; the browser half ships
+ * via exports["./client"], discovered through the package.json hydra.client
+ * declaration.
+ */
+/** Host plugin body — no host-side behavior for the slash trigger plugin. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-client-ui-input-trigger`.
+ * @module @hydraharness/harness-client-ui-input-trigger/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-ui-input-trigger-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map