open-index/open-npm huggingface dataset:
npm package: @sharpee/core
Description: Core functionality for the Sharpee interactive fiction engine
Author: Sharpee Team
Latest version: 0.9.107

# @sharpee/core

Core types, interfaces, and utilities for the Sharpee Interactive Fiction platform.

## Installation

```bash
npm install @sharpee/core
```

## Overview

This package provides the foundational types used across all Sharpee packages:

- **Event System** - `SemanticEvent`, typed event registry, event helpers
- **Query System** - `QueryManager` for player input (yes/no, menus)
- **Platform Events** - Save, restore, quit, restart handling
- **Core Utilities** - Common interfaces and type definitions

## Usage

```typescript
import {
  SemanticEvent,
  createTypedEvent,
  isEventType,
  QueryManager,
  PlatformEventType
} from '@sharpee/core';

// Create typed events
const event = createTypedEvent('game.started', { timestamp: Date.now() });

// Type-safe event checking
if (isEventType(event, 'game.started')) {
  console.log(event.data.timestamp);
}
```

## Related Packages

- [@sharpee/sharpee](https://www.npmjs.com/package/@sharpee/sharpee) - Full platform bundle
- [@sharpee/engine](https://www.npmjs.com/package/@sharpee/engine) - Game runtime
- [@sharpee/world-model](https://www.npmjs.com/package/@sharpee/world-model) - Entity system

## License

MIT
npm package: @sharpee/event-processor
Description: Event processor for applying semantic events to the world model
Author: Sharpee Team
Latest version: 0.9.107

# @sharpee/event-processor

Event processing and state application for the Sharpee Interactive Fiction platform.

## Installation

```bash
npm install @sharpee/event-processor
```

## Overview

Applies semantic events to the world model:

- **Event Application** - Updates world state based on events
- **Event Ordering** - Ensures consistent state transitions
- **Side Effects** - Triggers handlers for event types

## Usage

```typescript
import { EventProcessor } from '@sharpee/event-processor';

const processor = new EventProcessor(world);

// Apply events from action execution
const updatedWorld = processor.apply(events);
```

## Event Flow

```
Player Input → Parser → Action → Events → EventProcessor → Updated World
```

## Related Packages

- [@sharpee/engine](https://www.npmjs.com/package/@sharpee/engine) - Game runtime
- [@sharpee/sharpee](https://www.npmjs.com/package/@sharpee/sharpee) - Full platform bundle

## License

MIT
npm package: @sharpee/if-domain
Description: Core domain model and contracts for Sharpee Interactive Fiction Platform
Author: Sharpee Team
Latest version: 0.9.107

# @sharpee/if-domain

Core domain model and contracts for the Sharpee Interactive Fiction Platform.

## Overview

This package contains the shared domain types, events, and contracts that define the Interactive Fiction domain model. It serves as the single source of truth for domain concepts used across the Sharpee platform.

## Contents

### Events (`events.ts`)
- `IFEvents` - Standard interactive fiction event constants
- `IFEventType` - Type-safe event type
- `IFEventCategory` - Event categorization for filtering and handling

### Contracts (`contracts.ts`)
- `EventHandler` - Function type for handling events
- `EventValidator` - Function type for validating events
- `EventPreviewer` - Function type for previewing event effects
- `WorldChange` - Interface for world state changes
- `ProcessedEvents` - Result of event processing
- `ProcessorOptions` - Event processing configuration

### Changes (`changes.ts`)
- `WorldChangeType` - Types of world state changes
- `ContentsOptions` - Options for querying entity contents
- `FindOptions` - Options for finding entities
- `WorldConfig` - World behavior configuration
- `WorldState` - World state storage interface

### Sequencing (`sequencing.ts`)
- `TurnPhase` - Phases of turn execution
- `EventSequence` - Sequencing information for events
- `SequencedEvent` - Event with sequence information
- `EventSequencer` - Interface for event sequencing

## Usage

```typescript
import { IFEvents, EventHandler, WorldChange } from '@sharpee/if-domain';

// Use event constants
const moveEvent = {
  type: IFEvents.ACTOR_MOVED,
  // ...
};

// Implement event handlers
const handleMove: EventHandler = (event, world) => {
  // Handle the event
};
```

## Design Principles

1. **Domain-Driven Design**: All types represent domain concepts, not technical implementations
2. **Single Source of Truth**: Event constants and core types defined once
3. **No Implementation**: Pure type definitions with no runtime code (except constants)
4. **Minimal Dependencies**: Only depends on @sharpee/core for base types

## Dependencies

- `@sharpee/core` - Core semantic event types

## Build Order

This package must be built after `core` but before:
- `world-model`
- `event-processor`
- `engine`
- `stdlib`
npm package: @sharpee/if-services
Description: Runtime service interfaces for Sharpee Interactive Fiction Platform
Author: Sharpee Team
Latest version: 0.9.107

# @sharpee/if-services

Runtime service interfaces for the Sharpee Interactive Fiction Platform.

## Purpose

This package provides runtime service interfaces that need access to the world model. It separates these interfaces from the pure domain package (`@sharpee/if-domain`) to maintain clean architectural boundaries.

## Contents

- **TextService**: Interface for text generation services that process game events and produce formatted output
- (Future) Audio service interfaces
- (Future) Graphics service interfaces  
- (Future) Analytics service interfaces

## Architecture

The if-services package acts as a bridge between:
- The pure domain model (`@sharpee/if-domain`)
- The world model (`@sharpee/world-model`)
- Runtime implementations that need both

This pattern ensures that domain packages remain pure and don't have runtime dependencies, while still providing typed interfaces for runtime services.

## Usage

```typescript
import { TextService, TextServiceContext } from '@sharpee/if-services';

// Implement the TextService interface
class MyTextService implements TextService {
  initialize(context: TextServiceContext): void {
    // Initialize with game context
  }
  
  processTurn(): TextOutput {
    // Generate output for the current turn
  }
  
  // ... other methods
}
```

## Dependencies

- `@sharpee/core`: Core event system
- `@sharpee/if-domain`: Domain types and contracts
- `@sharpee/world-model`: World state management
npm package: @sharpee/lang-en-us
Description: English language implementation for Sharpee IF Engine
Author: Sharpee Team
Latest version: 0.9.107

# @sharpee/lang-en-us

English (US) language plugin for the Sharpee Interactive Fiction engine.

## Installation

```bash
npm install @sharpee/lang-en-us
```

## Usage

### In a Story

```typescript
import { EnglishLanguageProvider } from '@sharpee/lang-en-us';

// Register with the engine during story setup
const languageProvider = new EnglishLanguageProvider();
```

### With Custom Configuration

```typescript
import { EnglishLanguagePlugin } from '@sharpee/lang-en-us';

const language = new EnglishLanguagePlugin({
  // Custom templates
  customTemplates: {
    'taking.report.success': 'You grab {item} with gusto!'
  },
  
  // Additional verb mappings
  customVerbs: [{
    action: IFActions.TAKING,
    verbs: ['snatch', 'yoink']
  }]
});
```

## Features

- Complete verb mappings for all standard IF actions
- Full English parser with:
  - Tokenization
  - Part-of-speech tagging
  - Lemmatization (word normalization)
  - Grammar analysis
  - Compound verb handling
- Message templates for all actions and events
- Proper article handling (a/an/the)
- Pluralization support
- Direction abbreviations (n/s/e/w)

## Architecture

This package is a plugin for `@sharpee/stdlib` and extends the base language classes:

- `EnglishLanguagePlugin` extends `BaseIFLanguagePlugin`
- `EnglishParser` extends `BaseIFParserPlugin`

## Extending

You can extend the English language plugin for regional variants or custom games:

```typescript
import { EnglishLanguagePlugin } from '@sharpee/lang-en-us';

class BritishEnglishPlugin extends EnglishLanguagePlugin {
  protected getDefaultLanguageCode() {
    return 'en-GB';
  }
  
  protected getDefaultLanguageName() {
    return 'English (UK)';
  }
  
  protected initializeLanguageData() {
    super.initializeLanguageData();
    
    // Add British spellings
    this.registerActionTemplates({
      'examining.report.basic': 'You examine {item} and see its colour is {color}.'
    });
  }
}
```

## Data Exports

The package exports its data for customization:

- `englishVerbs` - All verb definitions
- `englishTemplates` - All message templates
- `englishWords` - Word lists (articles, prepositions, etc.)
- `irregularPlurals` - Irregular plural mappings
- `abbreviations` - Common abbreviations

## License

MIT
npm package: @sharpee/parser-en-us
Description: English (US) parser for Sharpee Interactive Fiction Platform
Author: Sharpee Team
Latest version: 0.9.107

# @sharpee/parser-en-us

English (US) parser for the Sharpee Interactive Fiction Platform.

## Installation

```bash
pnpm add @sharpee/parser-en-us
```

## Usage

```typescript
import { EnglishParser } from '@sharpee/parser-en-us';
import { ParserFactory } from '@sharpee/stdlib';
import { EnglishLanguageProvider } from '@sharpee/lang-en-us';

// Register the parser
ParserFactory.registerParser('en-US', EnglishParser);

// Create language provider
const language = new EnglishLanguageProvider();

// Create parser instance
const parser = ParserFactory.createParser('en-US', language);

// Parse commands
const result = parser.parse('take the red ball');
if (result.success) {
  console.log(result.value.action); // 'if.action.taking'
  console.log(result.value.structure.directObject?.text); // 'the red ball'
}
```

## Features

### Compound Verbs
- "look at" → examining
- "pick up" → taking  
- "put down" → dropping
- "turn on/off" → switching on/off

### Rich Information Preservation
- Articles preserved: "the", "a", "an"
- Modifiers tracked: "red", "small", "wooden"
- Position information for all tokens
- Original text reconstructible

### Grammar Patterns
- `VERB_ONLY`: "look", "wait"
- `VERB_NOUN`: "take ball", "examine mirror"
- `VERB_PREP_NOUN`: "look at painting"
- `VERB_NOUN_PREP_NOUN`: "put ball in box"
- `DIRECTION_ONLY`: "north", "n"

### Abbreviations
- Verb abbreviations: "x" → "examine", "l" → "look"
- Direction abbreviations: "n" → "north", "se" → "southeast"

## Parsed Command Structure

```typescript
interface ParsedCommand {
  rawInput: string;
  tokens: Token[];
  structure: {
    verb: VerbPhrase;
    directObject?: NounPhrase;
    preposition?: PrepPhrase;
    indirectObject?: NounPhrase;
  };
  pattern: string;
  confidence: number;
  action: string;
}
```

### Example Output

Input: "put the small key in the wooden box"

```json
{
  "action": "if.action.putting",
  "structure": {
    "verb": {
      "text": "put",
      "head": "put"
    },
    "directObject": {
      "text": "the small key",
      "head": "key",
      "articles": ["the"],
      "modifiers": ["small"],
      "candidates": ["key"]
    },
    "preposition": {
      "text": "in"
    },
    "indirectObject": {
      "text": "the wooden box",
      "head": "box",
      "articles": ["the"],
      "modifiers": ["wooden"],
      "candidates": ["box"]
    }
  },
  "pattern": "VERB_NOUN_PREP_NOUN",
  "confidence": 0.7
}
```

## English-Specific Features

- **SVO Word Order**: Subject-Verb-Object parsing
- **Articles**: "the", "a", "an" handling
- **Determiners**: "all", "every", "some"
- **Compound Prepositions**: Multi-word verb phrases
- **Flexible Adjective Placement**: "red ball" or "ball that is red"

## License

MIT
npm package: @sharpee/transcript-tester
Description: Transcript-based testing tool for Sharpee interactive fiction
Author: Sharpee Team
Latest version: 0.9.107

# @sharpee/transcript-tester

Transcript-based integration testing for Sharpee interactive fiction stories. Write tests that read like gameplay transcripts — player commands paired with assertions on text output, semantic events, and world state.

## Quick Start

```bash
# Published stories: build and test in one step
npx sharpee build --test

# Sharpee development: use the pre-built bundle (~170ms load)
node dist/cli/sharpee.js --test stories/my-story/tests/transcripts/*.transcript
```

## Example

```
title: Locked Door
story: my-story
description: Verify the brass key unlocks the cellar door

---

> examine door
[OK: contains "locked"]
[EVENT: true, type="if.event.examined"]

> unlock door with brass key
[OK: contains "unlocked"]
[STATE: true, door.isLocked = false]

> open door
[EVENT: true, type="if.event.opened"]
```

## Features

- **Text assertions** — `[OK: contains "..."]`, `[OK: not contains "..."]`, `[OK: matches /regex/]`
- **Event assertions** — Verify semantic events by type, position, and data
- **State assertions** — Check entity properties and inventory after commands
- **Control flow** — `GOAL/END GOAL`, `IF/END IF`, `WHILE/END WHILE`, `DO/UNTIL`, `RETRY`
- **Save/restore** — Checkpoint world state for walkthrough chaining
- **Navigation** — `[NAVIGATE TO: "Room"]` auto-pathfinds via BFS
- **Test commands** — `$teleport`, `$take`, `$kill`, `$immortal` for quick setup

## Documentation

For the full guide covering syntax, assertions, directives, CLI flags, and best practices:

**[Transcript Testing Guide](../../docs/guides/transcript-testing.md)**

Architecture decisions:
- [ADR-073: Transcript Story Testing](../../docs/architecture/adrs/adr-073-transcript-story-testing.md)
- [ADR-092: Smart Transcript Directives](../../docs/architecture/adrs/adr-092-smart-transcript-directives.md)

## Package Structure

| File | Purpose |
|------|---------|
| `src/parser.ts` | Parses `.transcript` files into structured test data |
| `src/runner.ts` | Executes transcripts against the game engine |
| `src/condition-evaluator.ts` | Evaluates condition expressions for directives |
| `src/navigator.ts` | BFS pathfinding for `NAVIGATE TO` |
| `src/reporter.ts` | Formats test results for terminal output |
| `src/cli.ts` | Standalone CLI entry point |
| `src/fast-cli.ts` | Bundle-optimized CLI (used by `dist/cli/sharpee.js`) |
| `src/types.ts` | TypeScript type definitions for transcripts, assertions, and directives |

## API

The package exports its parser and runner for programmatic use:

```typescript
import { parseTranscript, TranscriptRunner } from '@sharpee/transcript-tester';

const transcript = parseTranscript(fileContents);
const runner = new TranscriptRunner(gameEngine);
const results = await runner.run(transcript);
```
npm package: @sharpee/world-model
Description: World model for Sharpee IF platform - entities, traits, and behaviors
Author: Sharpee Team
Latest version: 0.9.107

# @sharpee/world-model

Entity system, traits, and behaviors for the Sharpee Interactive Fiction platform.

## Installation

```bash
npm install @sharpee/world-model
```

## Overview

The world model provides the foundation for game state:

- **Entities** - Rooms, objects, NPCs, and the player
- **Traits** - Composable properties (Openable, Lockable, Container, etc.)
- **Behaviors** - Reusable logic (LightSource, Wearable, Edible, etc.)
- **State Management** - Immutable world state with entity relationships

## Usage

```typescript
import {
  WorldModel,
  IFEntity,
  OpenableTrait,
  ContainerTrait
} from '@sharpee/world-model';

// Create entities with traits
const chest = world.createEntity('object', {
  id: 'treasure-chest',
  name: 'treasure chest',
  traits: [OpenableTrait, ContainerTrait]
});

// Query relationships
const contents = world.getContents(chest);
const location = world.getLocation(player);
```

## Traits

| Trait | Description |
|-------|-------------|
| `OpenableTrait` | Can be opened/closed |
| `LockableTrait` | Can be locked/unlocked with a key |
| `ContainerTrait` | Can contain other objects |
| `SupporterTrait` | Objects can be placed on top |
| `WearableTrait` | Can be worn by player/NPCs |
| `EdibleTrait` | Can be eaten |
| `LightSourceTrait` | Provides illumination |

## Related Packages

- [@sharpee/stdlib](https://www.npmjs.com/package/@sharpee/stdlib) - Standard actions
- [@sharpee/sharpee](https://www.npmjs.com/package/@sharpee/sharpee) - Full platform bundle

## License

MIT
npm package: @sharpen-com/kezuri
Description: The Sharpen Design System
Latest version: 0.14.3

# Kezuri: The Sharpen Design System

> 削り - _kezuri_ - shavings, cuttings

## Usage

* [Kezuri Storybook Documentation](https://coggen.github.io/kezuri/)

Kezuri is [deployed to npm](https://www.npmjs.com/package/@sharpen-com/kezuri)
and [served via jsDelivr CDN](https://www.jsdelivr.com/package/npm/@sharpen-com/kezuri).

In short, we include Kezuri's JS and CSS from the CDN in our application template.

```
<script src="https://cdn.jsdelivr.net/npm/@sharpen-com/kezuri@0/dist/kezuri/kezuri.esm.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@sharpen-com/kezuri@0/dist/kezuri/kezuri.min.css">
```

(By only specifying the _major_ version in the URL, Sharpen apps will
automatically use new _minor_ and _patch_ versions. [Learn more about
specifying versions in the URL](https://www.jsdelivr.com/documentation#id-load-exact-version).)

## Development

First, clone the repository and install dependencies with `npm install`.

### Run Storybook

```
$ npm run storybook
```

The Kezuri Storybook site will appear in your browser at `http://localhost:6006/`.

### Run a local dev server

```
$ npm run start
```

The web page at `src/index.html` will appear in your browser at `http://localhost:3333/`.

You can build new prototypes in the `src/prototypes` folder; add a new entry
to the table in `src/index.html` with a link.

### Add a new component

```
$ npx stencil g sharpen-component-name
```

Your component's tag name must start with `sharpen-`.

The generator will ask you which files to generate. This allows you to bootstrap
a stylesheet as well as spec and e2e tests along with the component file.

All components will be generated within the `src/components` directory: a
sub-directory will be created with the same name as the component tag name you
provided, and within that folder the files will be generated. 

Some guidance on component development:

* Rename the `css` file to `scss` since we use Sass.
* In your `@Component` metadata, remove the `shadow` setting since we do not use the Shadow DOM (unless you absolutely need it).

### Review

* Whenever you push code to Github, it will get compiled by Chromatic.
* Create a pull request and Chromatic will facilitate a UI review process.
* TODO: When we create a Github release, it will get pushed to npm

## Choices

* We define *standard design tokens* as CSS custom properties in `src/scss/tokens/tokens.scss`.
* We generate a set of *utility CSS classes* in `src/index.scss` that can be used by Kezuri's components or in other contexts.
* Nearly every web browser supports the WOFF2 web font format, so for best performance, we're only including that one file per font.

## Inspirations

* [You might not need shadow DOM](https://www.hjorthhansen.dev/you-might-not-need-shadow-dom/)
* [Styling Web Components Using A Shared Style Sheet](https://www.smashingmagazine.com/2016/12/styling-web-components-using-a-shared-style-sheet/)