Secret Sequence Core

A headless stratagem-style input engine for React.

Inspired by the input systems seen in games like Helldivers 2, this hook allows you to detect directional sequences and key combinations with timeout handling, progress tracking, and multi-sequence support.

Why?

Perfect for:

• 🎮 Easter eggs & game-like web experiences
• 🔐 Hidden admin panels
• 🛠 Developer shortcuts
• 🧩 Interactive UI systems
• ⚡ Stratagem-style input patterns

Installation

npm

npm install secret-sequence-core

pnpm

pnpm add secret-sequence-core

yarn

yarn add secret-sequence-core

bun

bun add secret-sequence-core

Quick Start

Stratagem-Style Input

import { useSecretSequence } from "secret-sequence-core"

function App() {
  const { progressMap } = useSecretSequence({
    sequences: [
      {
        id: "orbitalStrike",
        sequence: ["right", "right", "up"],
        onSuccess: () => deployStrike(),
      },
    ],
    timeout: 2000,
  })

  return <p>Input: {progressMap["orbitalStrike"]} / 3</p>
}

Konami Code

useSecretSequence({
  sequences: [
    {
      id: "konami",
      sequence: ["up", "up", "down", "down", "left", "right", "left", "right"],
      onSuccess: () => alert("🎉 Konami Code activated!"),
    },
  ],
  timeout: 3000,
})

Key Combo Shortcut

useSecretSequence({
  sequences: [
    {
      sequence: [{ key: "k", ctrl: true }],
      onSuccess: () => console.log("Shortcut triggered"),
    },
  ],
})

Multiple Sequences

const { progressMap } = useSecretSequence({
  sequences: [
    {
      id: "konami",
      sequence: ["up", "up", "down", "down", "left", "right", "left", "right"],
      onSuccess: () => console.log("Konami!"),
    },
    {
      id: "unlock",
      sequence: [
        { key: "k", ctrl: true },
        { key: "u", ctrl: true },
      ],
      onSuccess: () => console.log("Ctrl+K → Ctrl+U unlocked!"),
    },
  ],
  onProgress: (id, progress) => {
    console.log(`Sequence "${id}" progress: ${progress}`)
  },
})

API

useSecretSequence(options)

Options

| Option | Type | Default | Description | | -------------- | ----------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------- | | sequences | SecretSequenceConfig[] | — | Array of sequence configurations to detect simultaneously | | timeout | number | 2000 | Milliseconds of inactivity before resetting all progress | | enabled | boolean | true | Enable or disable all detection | | ignoreInputs | boolean | true | Ignore key events when focus is on <input>, <textarea>, or contentEditable elements | | onProgress | (id: string \| undefined, progress: number) => void | — | Callback fired on each correct step |

SecretSequenceConfig

| Property | Type | Description | | ----------- | --------------------- | ------------------------------------------------------------ | | id | string (optional) | Unique identifier for the sequence (defaults to array index) | | sequence | SequenceStep[] | Steps to detect | | onSuccess | () => void | Callback fired when the full sequence is completed |

Types

type Direction = "up" | "down" | "left" | "right"

type KeyCombo = {
  key: string
  ctrl?: boolean
  shift?: boolean
  alt?: boolean
  meta?: boolean
}

type SequenceStep = Direction | KeyCombo

A SequenceStep can be either:

• A Direction string (mapped to arrow keys)
• A KeyCombo object for any key with optional modifier keys

Return Value

| Property | Type | Description | | ------------- | ------------------------ | ------------------------------------------------- | | progressMap | Record<string, number> | Current progress for each sequence, keyed by id | | reset | () => void | Manually reset all sequences |

SSR Compatibility

This hook is safe to use in SSR environments like Next.js and Remix.

It guards against accessing window during server rendering and only attaches listeners on the client.

Features

• ✅ Multi-sequence detection
• ✅ Directional + key combo support
• ✅ Timeout-based reset
• ✅ Independent progress tracking
• ✅ Headless (bring your own UI)
• ✅ SSR-safe
• ✅ Fully typed with TypeScript
• ✅ Tree-shakeable
• ✅ Zero dependencies beyond React

Roadmap

• [ ] Smart partial matching (KMP algorithm)
• [ ] Advanced touch gesture support
• [ ] Custom event targets
• [ ] Devtools debug mode
• [ ] Optional UI companion package

Inspiration

Inspired by the stratagem input system in Helldivers 2 — where players input directional sequences under pressure to call in tactical support.

This hook brings that same pattern to the web: fast, sequential, multi-pattern input detection.

Contributing

Contributions, issues and feature requests are welcome.

Feel free to open an issue or submit a pull request.

License

MIT © Diego0Alonso