@sriinnu/harmon-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Harmon Core - Session engine, ranking, and adaptation
+ */
+export { createEngine } from './engine.js';
+export { rankTracks } from './ranking.js';
+export { fetchCandidates } from './sources.js';
+export { calculateArcModulation } from './arc.js';
+export { checkRecencyPenalty, getRecentPlays, getRecentArtists } from './history.js';
+export type { SessionEngine, EngineConfig, } from './engine.js';
+export type { AudioFeatures, MusicProvider, PlaybackController, TrackWithFeatures, PlayRecord, SessionState, EngineEvent, EventCallback, EngineLogger, RankedTrack, SessionStore, SourcesConfig, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErF,YAAY,EACV,aAAa,EACb,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * Harmon Core - Session engine, ranking, and adaptation
+ */
+export { createEngine } from './engine.js';
+export { rankTracks } from './ranking.js';
+export { fetchCandidates } from './sources.js';
+export { calculateArcModulation } from './arc.js';
+export { checkRecencyPenalty, getRecentPlays, getRecentArtists } from './history.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/ranking.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Two-phase track ranking algorithm
+ */
+import type { SessionPolicy } from '@sriinnu/harmon-protocol';
+import type { TrackWithFeatures, PlayRecord, RankedTrack } from './types.js';
+/**
+ * Two-phase ranking:
+ * 1. Hard constraint filtering (pass/fail)
+ * 2. Soft weight scoring (0-1 score)
+ *
+ * @param candidates Candidate tracks to rank
+ * @param policy Session policy
+ * @param history Play history
+ * @param elapsedMs Elapsed session time in milliseconds
+ * @returns Ranked tracks sorted by score (descending)
+ */
+export declare function rankTracks(candidates: TrackWithFeatures[], policy: SessionPolicy, history: PlayRecord[], elapsedMs: number): Promise<RankedTrack[]>;
+//# sourceMappingURL=ranking.d.ts.map

package/dist/ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranking.d.ts","sourceRoot":"","sources":["../src/ranking.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI7E;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,iBAAiB,EAAE,EAC/B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,UAAU,EAAE,EACrB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,EAAE,CAAC,CA0BxB"}

package/dist/ranking.js

@@ -0,0 +1,143 @@
+/**
+ * Two-phase track ranking algorithm
+ */
+import { calculateArcModulation } from './arc.js';
+import { checkRecencyPenalty } from './history.js';
+/**
+ * Two-phase ranking:
+ * 1. Hard constraint filtering (pass/fail)
+ * 2. Soft weight scoring (0-1 score)
+ *
+ * @param candidates Candidate tracks to rank
+ * @param policy Session policy
+ * @param history Play history
+ * @param elapsedMs Elapsed session time in milliseconds
+ * @returns Ranked tracks sorted by score (descending)
+ */
+export async function rankTracks(candidates, policy, history, elapsedMs) {
+    // Phase 1: Hard constraints
+    const filtered = candidates.filter(candidate => passesHardConstraints(candidate, policy));
+    if (filtered.length === 0) {
+        return [];
+    }
+    // Phase 2: Soft scoring
+    const scored = filtered.map(track => {
+        const score = calculateSoftScore(track, policy, history, elapsedMs);
+        const reason = buildScoreReason(track, score);
+        return {
+            track,
+            score,
+            reason,
+        };
+    });
+    // Sort descending by score
+    scored.sort((a, b) => b.score - a.score);
+    return scored;
+}
+/**
+ * Phase 1: Hard constraint filtering
+ */
+function passesHardConstraints(track, policy) {
+    const hard = policy.hard || {};
+    const features = track.features;
+    // No vocals check
+    if (hard.noVocals && features.instrumentalness < 0.5) {
+        return false;
+    }
+    // Explicit content check
+    if (hard.explicit === 'avoid' && track.explicit === true) {
+        return false;
+    }
+    if (hard.explicit === 'require' && track.explicit !== true) {
+        return false;
+    }
+    // Tempo range
+    if (hard.tempo) {
+        if (hard.tempo.min !== undefined && features.tempo < hard.tempo.min) {
+            return false;
+        }
+        if (hard.tempo.max !== undefined && features.tempo > hard.tempo.max) {
+            return false;
+        }
+    }
+    // Energy range
+    if (hard.energy) {
+        if (hard.energy.min !== undefined && features.energy < hard.energy.min) {
+            return false;
+        }
+        if (hard.energy.max !== undefined && features.energy > hard.energy.max) {
+            return false;
+        }
+    }
+    // Instrumentalness minimum
+    if (hard.instrumentalnessMin !== undefined) {
+        if (features.instrumentalness < hard.instrumentalnessMin) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Phase 2: Soft scoring (0-1)
+ */
+function calculateSoftScore(track, policy, history, elapsedMs) {
+    const soft = policy.soft || {};
+    const weights = soft.weights || {};
+    const features = track.features;
+    let score = 0;
+    let totalWeight = 0;
+    // Energy weight (with arc modulation)
+    if (typeof weights.energy === 'number') {
+        const arcMod = calculateArcModulation(elapsedMs, soft.arc, policy.durationMs);
+        const targetEnergy = 0.5 + arcMod; // Base 0.5, modified by arc
+        const energyScore = 1 - Math.abs(features.energy - targetEnergy);
+        score += weights.energy * energyScore;
+        totalWeight += Math.abs(weights.energy);
+    }
+    // Instrumentalness weight
+    if (typeof weights.instrumentalness === 'number') {
+        score += weights.instrumentalness * features.instrumentalness;
+        totalWeight += Math.abs(weights.instrumentalness);
+    }
+    // Speechiness weight (usually negative)
+    if (typeof weights.speechiness === 'number') {
+        const speechScore = weights.speechiness > 0
+            ? features.speechiness
+            : (1 - features.speechiness);
+        score += Math.abs(weights.speechiness) * speechScore;
+        totalWeight += Math.abs(weights.speechiness);
+    }
+    // Valence weight
+    if (typeof weights.valence === 'number') {
+        score += weights.valence * features.valence;
+        totalWeight += Math.abs(weights.valence);
+    }
+    // Acousticness weight
+    if (typeof weights.acousticness === 'number') {
+        score += weights.acousticness * features.acousticness;
+        totalWeight += Math.abs(weights.acousticness);
+    }
+    // Tempo weight (normalized to 0-1, assuming 60-180 BPM range)
+    if (typeof weights.tempo === 'number') {
+        const normalizedTempo = clamp((features.tempo - 60) / 120, 0, 1);
+        score += weights.tempo * normalizedTempo;
+        totalWeight += Math.abs(weights.tempo);
+    }
+    // Normalize by total weight
+    if (totalWeight > 0) {
+        score = score / totalWeight;
+    }
+    // Clamp to [0,1] BEFORE applying penalty (prevents negative * penalty inversion)
+    score = clamp(score, 0, 1);
+    // Apply recency penalty
+    const recencyPenalty = checkRecencyPenalty(track, history, policy.limits);
+    score = score * (1 - recencyPenalty);
+    return clamp(score, 0, 1);
+}
+function buildScoreReason(track, score) {
+    return `${track.name} scored ${score.toFixed(3)}`;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+//# sourceMappingURL=ranking.js.map

package/dist/ranking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranking.js","sourceRoot":"","sources":["../src/ranking.ts"],"names":[],"mappings":"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"}

package/dist/sources.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Candidate fetching from music providers (provider-agnostic)
+ */
+import type { MusicProvider, SourcesConfig, TrackWithFeatures, EngineLogger } from './types.js';
+/**
+ * Fetch candidate tracks from configured sources
+ *
+ * @param provider Music provider (Spotify, Apple Music, YouTube Music, etc.)
+ * @param sources Sources configuration
+ * @param targetCount Target number of candidates
+ * @returns Array of tracks with audio features
+ */
+export declare function fetchCandidates(provider: MusicProvider, sources: SourcesConfig, targetCount: number, logger?: EngineLogger): Promise<TrackWithFeatures[]>;
+//# sourceMappingURL=sources.d.ts.map

package/dist/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,iBAAiB,EAAiB,YAAY,EAAE,MAAM,YAAY,CAAC;AAS/G;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,aAAa,EACtB,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CA6F9B"}

package/dist/sources.js

@@ -0,0 +1,186 @@
+/**
+ * Candidate fetching from music providers (provider-agnostic)
+ */
+/** Default features for tracks from providers without audio analysis (Apple Music, YouTube Music) */
+const DEFAULT_FEATURES = {
+    energy: 0.5, instrumentalness: 0.1, speechiness: 0.1, valence: 0.5,
+    acousticness: 0.3, tempo: 120, danceability: 0.5, liveness: 0.2,
+    loudness: -8, key: 5, mode: 1, timeSignature: 4,
+};
+/**
+ * Fetch candidate tracks from configured sources
+ *
+ * @param provider Music provider (Spotify, Apple Music, YouTube Music, etc.)
+ * @param sources Sources configuration
+ * @param targetCount Target number of candidates
+ * @returns Array of tracks with audio features
+ */
+export async function fetchCandidates(provider, sources, targetCount, logger) {
+    const candidates = [];
+    const perSource = Math.ceil(targetCount / countActiveSources(sources));
+    // Liked/library tracks
+    if (sources.likedTracks) {
+        const tracks = await fetchSourceTracks('liked tracks', () => provider.getLibraryTracks({ limit: perSource }), logger);
+        const withFeatures = await enrichWithFeatures(provider, tracks, logger);
+        candidates.push(...withFeatures);
+    }
+    // Top tracks
+    if (sources.topTracks) {
+        const tracks = await fetchSourceTracks('top tracks', () => provider.getTopTracks({ limit: perSource }), logger);
+        const withFeatures = await enrichWithFeatures(provider, tracks, logger);
+        candidates.push(...withFeatures);
+    }
+    // Recent plays
+    if (sources.recentPlays) {
+        const tracks = await fetchSourceTracks('recent plays', () => provider.getRecentlyPlayed({ limit: perSource }), logger);
+        const withFeatures = await enrichWithFeatures(provider, tracks, logger);
+        candidates.push(...withFeatures);
+    }
+    // Search-seeded sources
+    if (sources.searchQueries && sources.searchQueries.length > 0) {
+        for (const query of sources.searchQueries.slice(0, 5)) {
+            const tracks = await fetchSourceTracks(`search ${query}`, () => provider.search(query, perSource), logger);
+            const withFeatures = await enrichWithFeatures(provider, tracks, logger);
+            candidates.push(...withFeatures);
+        }
+    }
+    // Seed playlists
+    if (sources.seedPlaylists && sources.seedPlaylists.length > 0) {
+        const seedPlaylists = sources.seedPlaylists;
+        for (const playlistId of sources.seedPlaylists.slice(0, 3)) {
+            const tracks = await fetchSourceTracks(`playlist ${playlistId}`, () => provider.getPlaylistTracks(extractId(playlistId), { limit: Math.ceil(perSource / seedPlaylists.length) }), logger);
+            const withFeatures = await enrichWithFeatures(provider, tracks, logger);
+            candidates.push(...withFeatures);
+        }
+    }
+    // Discovery via recommendations
+    if (sources.discovery?.enabled) {
+        const discoveryCount = Math.ceil(targetCount * (sources.discovery.ratio || 0.15));
+        const seedTracks = candidates.slice(0, 5).map((track) => track.id);
+        if (seedTracks.length > 0) {
+            const recommendations = await fetchSourceTracks('recommendations', () => provider.getRecommendations({
+                seedTrackIds: seedTracks,
+                limit: discoveryCount,
+            }), logger);
+            const withFeatures = await enrichWithFeatures(provider, recommendations, logger);
+            candidates.push(...withFeatures);
+        }
+    }
+    // Deduplicate by track ID
+    return deduplicateTracks(candidates);
+}
+/**
+ * I isolate one provider source failure so one unsupported capability does not
+ * wipe out the rest of the candidate collection pass.
+ */
+async function fetchSourceTracks(sourceName, loader, logger) {
+    try {
+        return await loader();
+    }
+    catch (error) {
+        if (!isExplicitlyUnsupportedSourceError(error)) {
+            throw error;
+        }
+        logger?.warn({ source: sourceName, error: error instanceof Error ? error.message : String(error) }, `Skipping source ${sourceName}`);
+        return [];
+    }
+}
+function isExplicitlyUnsupportedSourceError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return /not implemented|not available/i.test(error.message);
+}
+/**
+ * Enrich tracks with audio features.
+ * Uses positional correspondence — provider.getTrackFeatures returns
+ * (AudioFeatures | null)[] with nulls preserved at correct indices.
+ */
+async function enrichWithFeatures(provider, tracks, logger) {
+    if (tracks.length === 0) {
+        return [];
+    }
+    const trackIds = tracks.map(t => t.id);
+    let featureResults = await provider.getTrackFeatures(trackIds);
+    // If the provider breaks positional correspondence, I prefer
+    // a safe full fallback over silently attaching the wrong features
+    // to the wrong tracks.
+    if (featureResults.length !== tracks.length) {
+        logger?.warn({ expected: tracks.length, received: featureResults.length }, 'Feature result length mismatch — falling back to defaults');
+        featureResults = Array.from({ length: tracks.length }, () => null);
+    }
+    // Match features to tracks by position (nulls preserved).
+    // Tracks without features get DEFAULT_FEATURES so non-Spotify providers still work.
+    const enriched = [];
+    for (let i = 0; i < tracks.length; i++) {
+        const feature = featureResults[i];
+        enriched.push({
+            ...tracks[i],
+            features: feature || DEFAULT_FEATURES,
+        });
+    }
+    return enriched;
+}
+/**
+ * Remove duplicate tracks by ID
+ */
+function deduplicateTracks(tracks) {
+    const seen = new Set();
+    const unique = [];
+    for (const track of tracks) {
+        if (!seen.has(track.id)) {
+            seen.add(track.id);
+            unique.push(track);
+        }
+    }
+    return unique;
+}
+/**
+ * Count active sources for distribution
+ */
+function countActiveSources(sources) {
+    let count = 0;
+    if (sources.likedTracks)
+        count++;
+    if (sources.topTracks)
+        count++;
+    if (sources.recentPlays)
+        count++;
+    if (sources.searchQueries && sources.searchQueries.length > 0)
+        count++;
+    if (sources.seedPlaylists && sources.seedPlaylists.length > 0)
+        count++;
+    if (sources.discovery?.enabled)
+        count++;
+    return Math.max(count, 1);
+}
+/**
+ * Extract provider ID from URI or URL
+ */
+function extractId(uri) {
+    // Spotify URIs
+    if (uri.startsWith('spotify:')) {
+        return uri.split(':').pop() || uri;
+    }
+    if (uri.startsWith('youtube:playlist:')) {
+        return uri.split(':').pop() || uri;
+    }
+    // Spotify/YouTube URLs
+    if (uri.includes('spotify.com/') || uri.includes('youtube.com/') || uri.includes('music.apple.com/')) {
+        try {
+            const url = new URL(uri);
+            const playlistId = url.searchParams.get('list');
+            if (playlistId) {
+                return playlistId;
+            }
+            const parts = url.pathname.split('/').filter(Boolean);
+            return parts[parts.length - 1] || uri;
+        }
+        catch {
+            const parts = uri.split('/');
+            return parts[parts.length - 1].split('?')[0];
+        }
+    }
+    return uri;
+}
+//# sourceMappingURL=sources.js.map

package/dist/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Internal types for harmon-core
+ */
+import type { TrackInfo, SessionPolicy } from '@sriinnu/harmon-protocol';
+/**
+ * Audio features for track ranking.
+ * Canonical definition — providers map their features to this shape.
+ * Providers that don't support features (YouTube Music) return null.
+ */
+export interface AudioFeatures {
+    energy: number;
+    instrumentalness: number;
+    speechiness: number;
+    valence: number;
+    acousticness: number;
+    tempo: number;
+    danceability: number;
+    liveness: number;
+    loudness: number;
+    key: number;
+    mode: number;
+    timeSignature: number;
+}
+/**
+ * Extended TrackInfo with audio features attached
+ */
+export interface TrackWithFeatures extends TrackInfo {
+    features: AudioFeatures;
+}
+/**
+ * Provider-agnostic interface for fetching music data.
+ * Each music service (Spotify, Apple Music, YouTube Music) implements this.
+ */
+export interface MusicProvider {
+    readonly name: 'spotify' | 'apple' | 'youtube' | 'local';
+    isConnected(): boolean;
+    /** Search for tracks */
+    search(query: string, limit?: number): Promise<TrackInfo[]>;
+    /** Get user's library/saved tracks */
+    getLibraryTracks(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<TrackInfo[]>;
+    /** Get user's top/most-played tracks */
+    getTopTracks(options?: {
+        limit?: number;
+        timeRange?: string;
+    }): Promise<TrackInfo[]>;
+    /** Get recently played tracks */
+    getRecentlyPlayed(options?: {
+        limit?: number;
+    }): Promise<TrackInfo[]>;
+    /** Get tracks from a specific playlist */
+    getPlaylistTracks(playlistId: string, options?: {
+        limit?: number;
+    }): Promise<TrackInfo[]>;
+    /** Get recommendations based on seed tracks */
+    getRecommendations(options: {
+        seedTrackIds?: string[];
+        limit?: number;
+    }): Promise<TrackInfo[]>;
+    /**
+     * Get audio features for tracks.
+     * Returns array with same length as trackIds. Null for tracks without features.
+     */
+    getTrackFeatures(trackIds: string[]): Promise<(AudioFeatures | null)[]>;
+}
+/**
+ * Provider-agnostic playback controller.
+ * Optional methods (seek, volume, etc.) may not be supported by all providers.
+ */
+export interface PlaybackController {
+    readonly name: 'spotify' | 'apple' | 'youtube' | 'local';
+    play(options?: {
+        uri?: string;
+        trackId?: string;
+    }): Promise<void>;
+    pause(): Promise<void>;
+    next(): Promise<void>;
+    previous(): Promise<void>;
+    seek?(positionMs: number): Promise<void>;
+    setVolume?(volumePercent: number): Promise<void>;
+    setShuffle?(state: boolean): Promise<void>;
+    setRepeat?(state: 'off' | 'track' | 'context'): Promise<void>;
+    getNowPlaying(): Promise<TrackInfo | null>;
+    addToQueue(trackUri: string, track?: TrackInfo): Promise<void>;
+}
+/**
+ * Track play record in history
+ */
+export interface PlayRecord {
+    trackId: string;
+    artistIds: string[];
+    playedAt: number;
+}
+/**
+ * Storage contract required by the session engine.
+ * I keep this narrow so harmon-core stays decoupled from any concrete store.
+ */
+export interface SessionStore {
+    createSession(policy: string): Promise<string>;
+    endSession(id: string): Promise<void>;
+    logEvent(type: string, payload: Record<string, unknown>, sessionId?: string): Promise<string>;
+}
+/**
+ * Session state managed by engine
+ */
+export interface SessionState {
+    id: string;
+    policy: SessionPolicy;
+    startedAt: number;
+    status: 'idle' | 'running' | 'paused';
+    history: PlayRecord[];
+    currentTrack: TrackInfo | null;
+    queuedTracks: TrackInfo[];
+}
+/**
+ * Event emitted by engine
+ */
+export interface EngineEvent {
+    type: 'session.started' | 'session.stopped' | 'session.nudged' | 'track.started' | 'queue.refilled' | 'error';
+    payload: Record<string, unknown>;
+}
+/**
+ * Event callback type
+ */
+export type EventCallback = (event: EngineEvent) => void;
+/**
+ * Minimal logger contract for engine internals.
+ * Matches the subset of pino that harmon-core actually uses,
+ * so the core package stays decoupled from any concrete logger.
+ */
+export interface EngineLogger {
+    warn(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Ranking result with score
+ */
+export interface RankedTrack {
+    track: TrackWithFeatures;
+    score: number;
+    reason: string;
+}
+/**
+ * Sources configuration for fetching candidates
+ */
+export interface SourcesConfig {
+    likedTracks?: boolean;
+    topTracks?: boolean;
+    recentPlays?: boolean;
+    searchQueries?: string[];
+    seedPlaylists?: string[];
+    seedArtists?: string[];
+    discovery?: {
+        enabled?: boolean;
+        ratio?: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Internal types for harmon-core
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/logo.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" fill="none">
+  <!-- I am the core mark: a small engine-heart with adjustment arms. -->
+  <rect width="64" height="64" rx="16" fill="#F3E7D4"/>
+  <g stroke="#171513" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M19 20L23 16"/>
+    <path d="M41 20L45 16"/>
+    <path d="M15 33H19"/>
+    <path d="M45 33H49"/>
+    <path d="M22 46L19 50"/>
+    <path d="M42 46L45 50"/>
+    <path d="M32 21C36 16 45 20 45 27C45 38 32 44 32 44C32 44 19 38 19 27C19 20 28 16 32 21Z"/>
+    <circle cx="32" cy="31" r="5"/>
+  </g>
+</svg>