webpreview

type DictationEngine string

type Engine interface {
	// Open starts a session. The caller owns it and must Close it.
	Open(ctx context.Context) (Session, error)
	// Describe returns a short human-readable engine label for the
	// preview banner and logs.
	Describe() string
}

type ExecEngine struct {
	Cmdline string
}

type ModelDownloadProgress func(file string, index, count int, done, total int64)

type Options struct {
	// UpstreamURL is the HTTP(S) origin the proxy fronts. Required.
	UpstreamURL *url.URL

	// DaemonSocketPath is the clank daemon's unix socket; /__clank/api/*
	// relays there. Required.
	DaemonSocketPath string

	// Token gates /__clank/api/* and /__clank/voice. The injected page
	// config carries it; nothing else on the machine learns it. This is
	// the same trust move as the LAN front door's pairing token, scoped
	// down to loopback.
	Token string

	// OverlayConfig is serialized into window.__CLANK_PREVIEW for the
	// overlay (session context: local_path, backend, hostname, name,
	// optional session_id). Token and voice availability are added here.
	OverlayConfig map[string]any

	// Engine powers local dictation; nil marks the local engine
	// unavailable in the overlay config and 503s the voice endpoint.
	// The overlay may still offer the browser's Web Speech API, which
	// it detects client-side.
	Engine Engine

	// DictationEngine is the persisted engine choice injected into the
	// overlay config. Empty means unchosen (the overlay asks on first
	// dictation); anything else must parse via ParseDictationEngine.
	DictationEngine DictationEngine

	// PersistDictationEngine stores a choice made in the overlay's
	// engine picker so it survives preview restarts. nil means choices
	// only last for this run.
	PersistDictationEngine func(DictationEngine) error

	// LauncherSeen suppresses the first-use coachmark. PersistLauncherSeen
	// stores the acknowledgement across auto-assigned preview ports.
	LauncherSeen        bool
	PersistLauncherSeen func() error

	// ListenPort for the proxy on 127.0.0.1; 0 picks a free port.
	ListenPort int

	Log *log.Logger
}

type Result struct {
	Text  string
	Final bool
	// Err reports a failed decode (Final implied). The session may
	// still accept the next utterance unless Results was closed.
	Err error
}

type Server struct {
	// URL is the browser-facing address, http://127.0.0.1:<port>.
	URL string
	// contains filtered or unexported fields
}

type Session interface {
	// Feed accepts PCM as it arrives from the mic.
	Feed(pcm []byte) error
	// End marks push-to-talk release: flush and decode; exactly one
	// Final Result follows on Results (empty text = heard nothing).
	End() error
	// Cancel discards audio buffered since the last End.
	Cancel() error
	// Results streams partial and final updates. Closed when the
	// session is Closed or the engine dies.
	Results() <-chan Result
	// Close releases the session and, for serializing engines, hands
	// the engine to the next Open.
	Close() error
}

type SherpaEngine struct {
	// Bin is the clank-voice executable path.
	Bin string
	// Args are passed verbatim (production: --models <dir>). Split out
	// so tests can substitute a fake binary with its own flags.
	Args []string
	// ReadyTimeout caps the model-load wait after spawn. Zero means
	// defaultReadyTimeout.
	ReadyTimeout time.Duration
	Log          *log.Logger
	// contains filtered or unexported fields
}