@microprompt/trigger-core

Shared trigger detection and validation for MicroPrompt clients (browser extension, IDE plugins, CLI tooling). This library is runtime-dependency-free: both dependencies and peerDependencies are intentionally empty so the package can be safely bundled into browser extensions and service workers without pulling a transitive graph.

Install

npm install @microprompt/trigger-core

Node 18+ is required (relies on global fetch and AbortController).

Minimal example

import { detectTriggers, TriggerValidator, TIER_COLORS } from '@microprompt/trigger-core';

const tokens = detectTriggers('Use mp:3c and comp:abc in this draft.');
// => [{ tier: 'mp', code: '3c', ... }, { tier: 'comp', code: 'abc', ... }]

const validator = new TriggerValidator({
  authToken: process.env.MP_AUTH_TOKEN!,
  daemonUrl: 'http://127.0.0.1:7720',
});

const resolved = await validator.validateAll(tokens);
for (const r of resolved) {
  console.log(r.tier, r.code, r.status, TIER_COLORS[r.tier].label);
}

API

detectTriggers(text: string): TriggerToken[]

Scans free text and returns every mp: / comp: / mcomp: trigger with its character offsets, tier, code, optional modifier, and optional budget hint. Non-matching prefixes (@mp:abc, #mp:abc) are rejected — those read like handles/hashtags, not triggers. Codes are normalised to lowercase.

Per-tier minimum code lengths (to avoid false positives on short words):

| Tier | Min | Max | | ------- | --- | --- | | mp | 2 | 7 | | comp | 3 | 7 | | mcomp | 4 | 7 |

The regex TRIGGER_REGEX is exported for callers that want to do their own scanning. It has the global flag set; detectTriggers resets lastIndex before each scan so concurrent callers don't interfere.

TriggerValidator

Resolves tokens against the local MicroPrompt daemon's GET /api/v1/resolve/:tier/:code endpoint and caches successful / 404 results per (tier, code) for cacheTTL ms.

new TriggerValidator({
  authToken: string,
  daemonUrl?: string,      // default 'http://127.0.0.1:7720'
  cacheTTL?: number,       // default 60_000 ms
  timeoutMs?: number,      // default 4_000 ms
  fetchImpl?: typeof fetch // injected for tests / service-workers
});

Methods:

• validate(token) — returns a single ResolvedTrigger.
• validateAll(tokens) — parallel Promise.all over validate.
• stats() — { hits, misses, entries } for diagnostics.
• clearCache() — wipe all cached entries (call when auth/URL change).

Transient errors (network failure, 5xx) are not cached so the next call can retry. A 250ms linear backoff with up to 3 attempts is applied to 5xx / network responses.

TIER_COLORS / INVALID_COLORS

Brand-palette TierConfig records for each tier, used by UI layers for hover cards and inline highlights.

TIER_COLORS.mp    === { background: '#F3E5F5', textColor: '#7B2D8E', ... }
TIER_COLORS.comp  === { background: '#E0F7FA', textColor: '#0097A7', ... }
TIER_COLORS.mcomp === { background: '#FFF3E0', textColor: '#E65100', ... }
INVALID_COLORS    === { background: '#FFEBEE', textColor: '#C62828', ... }

Modifier table

Modifiers select which rendering of a prompt the daemon should return. The daemon applies the modifier at resolve time; the validator cache is modifier-agnostic because modifiers change detail, not identity.

| Suffix | Meaning | Example | | ------ | ---------- | ---------------- | | ~ | summary | mp:abc~ | | ! | extended | mp:abc! | | ? | preview | mp:abc? |

Modifiers may be followed by a positive integer budget hint (token count), e.g. mp:abc~512. The hint is surfaced on TriggerToken.budgetHint and is also forwarded by the daemon contract.

Cache TTL behaviour

• Successful resolves cached per (tier, code) for cacheTTL ms.
• 404 (not_found) responses cached the same way — prevents hammering the daemon for known-missing codes within the TTL window.
• Transient errors (network failure, 5xx) are not cached.
• The cache key ignores modifier and budgetHint — the daemon re-applies them on every call.
• Call clearCache() when the auth token or daemon URL changes.

Daemon contract

GET {daemonUrl}/api/v1/resolve/:tier/:code

Headers: Authorization: Bearer <token>

Response (200):

{
  "title": "string",
  "content": "string",
  "version": 1,
  "blake3_hash": "hex",
  "tags": ["tag"],
  "updated_at": "ISO-8601"
}

Response (404): trigger is unknown — cached as status: 'not_found'. Response (5xx / network failure): retried with 250ms linear backoff (max 3 attempts), then returned as status: 'error' without caching.

Also used: GET /health — returns { prompt_count: number } and is consumed by the browser extension popup's "Test connection" button.