Document markup and improve choice tags

src/engine/ink-engine.ts

@@ -150,11 +150,13 @@ export class InkEngine {
 
     const paragraphs: TurnResult['paragraphs'] = [];
     const globalTags: StoryTag[] = [];
+    const turnTags: StoryTag[] = [];
 
     while (this.story.canContinue) {
       const rawText = this.story.Continue();
       const text = String(rawText || '').trim();
       const tags = parseTags(this.story.currentTags || []);
+      turnTags.push(...tags);
 
       tags
         .filter((tag) => tag.key === 'title' || tag.key === 'author')
@@ -170,7 +172,7 @@ export class InkEngine {
     const choices = this.story.currentChoices.map((choice): ChoiceResult => {
       const tags = parseTags(choice.tags || []);
       const category = getTagValue(tags, 'action');
-      const letter = getTagValue(tags, 'letter');
+      const letter = getTagValue(tags, 'letter') || getTagValue(tags, 'key');
       return {
         index: choice.index,
         text: String(choice.text || '').trim(),
@@ -179,13 +181,46 @@ export class InkEngine {
         letter,
       };
     });
+    const inputMode = choices.length > 0 ? 'choice' : 'end';
+    const gameState: TurnResult['gameState'] = {};
+
+    if (inputMode === 'end') {
+      const errorTag = turnTags.find((tag) => tag.key === 'error');
+      const scoreTag = turnTags.find((tag) => tag.key === 'score');
+
+      if (!errorTag && !scoreTag) {
+        const message = 'Ink story ended without an explicit #score ending tag.';
+        const generatedErrorTag: StoryTag = { key: 'error', value: message };
+        globalTags.push(generatedErrorTag);
+        turnTags.push(generatedErrorTag);
+      }
+
+      const finalErrorTag = turnTags.find((tag) => tag.key === 'error');
+      const finalScoreTag = turnTags.find((tag) => tag.key === 'score');
+      if (finalErrorTag) {
+        gameState.endState = {
+          type: 'error',
+          message: finalErrorTag.value || finalErrorTag.param,
+        };
+      } else if (finalScoreTag) {
+        const numericScore = Number(finalScoreTag?.value);
+        if (Number.isFinite(numericScore)) {
+          gameState.score = numericScore;
+        }
+        gameState.endState = {
+          type: 'intended',
+          message: finalScoreTag.value || finalScoreTag.param,
+        };
+      }
+    }
 
     return {
       turnId: this.nextTurnId++,
       paragraphs,
       choices,
-      inputMode: choices.length > 0 ? 'choice' : 'end',
+      inputMode,
       globalTags: globalTags.length > 0 ? globalTags : undefined,
+      gameState: Object.keys(gameState).length > 0 ? gameState : undefined,
     };
   }
 }