@rohal12/spindle-lsp 0.5.4 → 0.7.0

package/dist/bin.js

@@ -210,6 +210,10 @@ var init_passage_index = __esm({
       getStoryVariables() {
         return this.getPassage("StoryVariables");
       }
+      /** Get the StoryTransients passage, if any. */
+      getStoryTransients() {
+        return this.getPassage("StoryTransients");
+      }
       /** Get the StoryInit passage, if any. */
       getStoryInit() {
         return this.getPassage("StoryInit");
@@ -412,14 +416,16 @@ var init_macro_registry = __esm({
 });
 
 // src/core/workspace/variable-tracker.ts
-var varRefRegex, EXCLUDED_PASSAGES, CLEAN_PATTERNS, VariableTracker;
+var varRefRegex, transientRefRegex, EXCLUDED_PASSAGES, CLEAN_PATTERNS, VariableTracker;
 var init_variable_tracker = __esm({
   "src/core/workspace/variable-tracker.ts"() {
     "use strict";
     init_passage_parser();
     varRefRegex = /\$([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)/g;
+    transientRefRegex = /(?<!\w)%([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)/g;
     EXCLUDED_PASSAGES = /* @__PURE__ */ new Set([
       "StoryVariables",
+      "StoryTransients",
       "StoryInit",
       "StoryData",
       "StoryScript",
@@ -442,8 +448,12 @@ var init_variable_tracker = __esm({
     VariableTracker = class {
       declared = /* @__PURE__ */ new Map();
       _hasStoryVariables = false;
+      declaredTransient = /* @__PURE__ */ new Map();
+      _hasStoryTransients = false;
       /** Per-URI list of variable usages. */
       usagesByUri = /* @__PURE__ */ new Map();
+      /** Per-URI list of transient variable usages. */
+      transientUsagesByUri = /* @__PURE__ */ new Map();
       /**
        * Parse the StoryVariables passage content for declarations.
        * Each line like `$name = value` becomes a declaration.
@@ -474,14 +484,46 @@ var init_variable_tracker = __esm({
           this.declared.set(name, decl);
         }
       }
+      /**
+       * Parse the StoryTransients passage content for declarations.
+       * Each line like `%name = value` becomes a declaration.
+       */
+      parseStoryTransients(content) {
+        this.declaredTransient.clear();
+        this._hasStoryTransients = true;
+        const lines = content.split("\n");
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || trimmed.startsWith("//") || trimmed.startsWith("<!--")) continue;
+          const match = /^%([A-Za-z_$][\w$]*)\s*=\s*(.*)$/.exec(trimmed);
+          if (!match) continue;
+          const name = match[1];
+          const expr = match[2].trim();
+          const decl = { name, sigil: "%" };
+          if (expr.startsWith("{")) {
+            const fieldRegex = /(\w+)\s*:/g;
+            let fieldMatch;
+            const fields = [];
+            while ((fieldMatch = fieldRegex.exec(expr)) !== null) {
+              fields.push(fieldMatch[1]);
+            }
+            if (fields.length > 0) {
+              decl.fields = fields;
+            }
+          }
+          this.declaredTransient.set(name, decl);
+        }
+      }
       /**
        * Scan a document for variable usages.
        * Identifies passages in the document and scans non-special ones.
        */
       scanDocument(uri, text, _macros) {
         this.usagesByUri.delete(uri);
+        this.transientUsagesByUri.delete(uri);
         const lines = text.split("\n");
         const usages = [];
+        const transientUsages = [];
         const passageBoundaries = [];
         for (let i = 0; i < lines.length; i++) {
           const header = parsePassageHeader(lines[i], i);
@@ -523,10 +565,32 @@ var init_variable_tracker = __esm({
             };
             usages.push({ uri, baseName, fullName, range });
           }
+          const tre = new RegExp(transientRefRegex.source, "g");
+          let tmatch;
+          while ((tmatch = tre.exec(cleaned)) !== null) {
+            const fullName = tmatch[1];
+            const baseName = fullName.split(".")[0];
+            const charOffset = tmatch.index;
+            let localLine = 0;
+            for (let i = 0; i < lineOffsets.length; i++) {
+              if (lineOffsets[i] > charOffset) break;
+              localLine = i;
+            }
+            const character = charOffset - lineOffsets[localLine];
+            const absoluteLine = contentStartLine + localLine;
+            const range = {
+              start: { line: absoluteLine, character },
+              end: { line: absoluteLine, character: character + tmatch[0].length }
+            };
+            transientUsages.push({ uri, baseName, fullName, range });
+          }
         }
         if (usages.length > 0) {
           this.usagesByUri.set(uri, usages);
         }
+        if (transientUsages.length > 0) {
+          this.transientUsagesByUri.set(uri, transientUsages);
+        }
       }
       /** Get all declared variables. */
       getDeclared() {
@@ -562,6 +626,40 @@ var init_variable_tracker = __esm({
       hasStoryVariables() {
         return this._hasStoryVariables;
       }
+      /** Get all declared transient variables. */
+      getDeclaredTransient() {
+        return this.declaredTransient;
+      }
+      /** Get all usages of a transient variable by base name. */
+      getTransientUsages(name) {
+        const results = [];
+        for (const usages of this.transientUsagesByUri.values()) {
+          for (const u of usages) {
+            if (u.baseName === name) {
+              results.push({ uri: u.uri, range: u.range });
+            }
+          }
+        }
+        return results;
+      }
+      /** Get undeclared transient variable usages in a specific document. */
+      getUndeclaredTransient(uri) {
+        const usages = this.transientUsagesByUri.get(uri);
+        if (!usages) return [];
+        const results = [];
+        const seen = /* @__PURE__ */ new Set();
+        for (const u of usages) {
+          if (!this.declaredTransient.has(u.baseName) && !seen.has(u.baseName)) {
+            seen.add(u.baseName);
+            results.push({ name: u.baseName, range: u.range });
+          }
+        }
+        return results;
+      }
+      /** Whether a StoryTransients passage has been parsed. */
+      hasStoryTransients() {
+        return this._hasStoryTransients;
+      }
     };
   }
 });
@@ -721,7 +819,7 @@ var variableInterpolationRegex, macroRegex;
 var init_macro_parser = __esm({
   "src/core/parsing/macro-parser.ts"() {
     "use strict";
-    variableInterpolationRegex = /(?<!\\)\{([$_@][A-Za-z_$][\w$.]*)\}/g;
+    variableInterpolationRegex = /(?<!\\)\{([$_@%][A-Za-z_$][\w$.]*)\}/g;
     macroRegex = /(?<!\\)\{(\/)?(?:((?:[#.][a-zA-Z][\w-]*\s*)*)([A-Za-z][\w-]*))(?:\s+((?:(?:`(?:\\.|[^`\\])*?`)|(?:"(?:\\.|[^"\\])*?")|(?:'(?:\\.|[^'\\])*?')|(?:\[(?:[<>]?[Ii][Mm][Gg])?\[[^\r\n]*?\]\]+)|[^}]|(?:}))*?))?\}/gmi;
   }
 });
@@ -799,12 +897,12 @@ var init_macro_supplements = __esm({
       },
       set: {
         name: "set",
-        description: "Sets variables based on the given expression.\n\nUsage: `{set $var to value}`\n\nSupports `$var` (story), `_var` (temporary), and `@var` (local) variables.",
+        description: "Sets variables based on the given expression.\n\nUsage: `{set $var to value}`\n\nSupports `$var` (story), `_var` (temporary), `@var` (local), and `%var` (transient) variables.",
         parameters: ["...text"]
       },
       unset: {
         name: "unset",
-        description: "Unsets one or more variables.\n\nUsage: `{unset $var}`",
+        description: "Unsets one or more variables.\n\nUsage: `{unset $var}`\n\nSupports `$var` (story), `_var` (temporary), `@var` (local), and `%var` (transient) variables.",
         parameters: ["...text"]
       },
       computed: {
@@ -1143,6 +1241,23 @@ var init_workspace_model = __esm({
             this.variables.parseStoryVariables(content);
           }
         }
+        const storyTransients = this.passages.getStoryTransients();
+        if (storyTransients) {
+          const text = this.documents.getText(storyTransients.uri);
+          if (text) {
+            const lines = text.split("\n");
+            const contentStart = storyTransients.headerEnd.end.line + 1;
+            let contentEnd = lines.length;
+            for (let i = contentStart; i < lines.length; i++) {
+              if (/^::\s+/.test(lines[i])) {
+                contentEnd = i;
+                break;
+              }
+            }
+            const content = lines.slice(contentStart, contentEnd).join("\n");
+            this.variables.parseStoryTransients(content);
+          }
+        }
         for (const uri of this.documents.getUris()) {
           const text = this.documents.getText(uri);
           if (text) {
@@ -1190,10 +1305,12 @@ var init_diagnostic_codes = __esm({
       UndeclaredVariable: "SP200",
       UndeclaredField: "SP201",
       NoStoryVariables: "SP202",
+      UndeclaredTransient: "SP203",
       BrokenPassageLink: "SP300",
       WidgetArgCountMismatch: "SP301",
       DeadEndPassage: "SP400",
-      UnreachablePassage: "SP401"
+      UnreachablePassage: "SP401",
+      LineTooLong: "SP500"
     };
     severityMap = {
       SP100: "warning",
@@ -1210,10 +1327,12 @@ var init_diagnostic_codes = __esm({
       SP200: "warning",
       SP201: "warning",
       SP202: "info",
+      SP203: "warning",
       SP300: "warning",
       SP301: "warning",
       SP400: "hint",
-      SP401: "hint"
+      SP401: "hint",
+      SP500: "warning"
     };
   }
 });
@@ -1409,7 +1528,7 @@ var varTestRegexp, EOF, Lexer, notSpaceRegex, spaceRegex;
 var init_argument_lexer = __esm({
   "src/core/parsing/argument-lexer.ts"() {
     "use strict";
-    varTestRegexp = /^[$_@][$A-Z_a-z][$0-9A-Z_.a-z]*/;
+    varTestRegexp = /^[$_@%][$A-Z_a-z][$0-9A-Z_.a-z]*/;
     EOF = -1;
     Lexer = class {
       source;
@@ -2092,7 +2211,7 @@ var init_link_parser = __esm({
 });
 
 // src/plugins/diagnostics.ts
-function computeDiagnostics(uri, workspace) {
+function computeDiagnostics(uri, workspace, options) {
   if (!workspace.initialized) return [];
   try {
     const text = workspace.documents.getText(uri);
@@ -2124,6 +2243,12 @@ function computeDiagnostics(uri, workspace) {
       validateWidgetInvocations(macros, workspace, diagnostics);
     } catch {
     }
+    if (options?.maxLineLength) {
+      try {
+        validateLineLength(text, passages, options.maxLineLength, diagnostics);
+      } catch {
+      }
+    }
     return diagnostics;
   } catch {
     return [];
@@ -2284,7 +2409,7 @@ function validateArguments(macros, workspace, passageNames, diagnostics) {
 }
 function validateVariables(uri, workspace, diagnostics) {
   if (!workspace.variables.hasStoryVariables()) {
-    const undeclared2 = workspace.variables.getUndeclared(uri);
+    const undeclared = workspace.variables.getUndeclared(uri);
     const text = workspace.documents.getText(uri);
     if (text && /\$[A-Za-z_$]/.test(text)) {
       const passages = workspace.passages.getPassagesInDocument(uri);
@@ -2300,15 +2425,25 @@ function validateVariables(uri, workspace, diagnostics) {
         ));
       }
     }
-    return;
+  } else {
+    const undeclared = workspace.variables.getUndeclared(uri);
+    for (const u of undeclared) {
+      diagnostics.push(makeDiag(
+        u.range,
+        DiagnosticCode.UndeclaredVariable,
+        `Variable '$${u.name}' is not declared in StoryVariables`
+      ));
+    }
   }
-  const undeclared = workspace.variables.getUndeclared(uri);
-  for (const u of undeclared) {
-    diagnostics.push(makeDiag(
-      u.range,
-      DiagnosticCode.UndeclaredVariable,
-      `Variable '$${u.name}' is not declared in StoryVariables`
-    ));
+  if (workspace.variables.hasStoryTransients()) {
+    const undeclaredTransient = workspace.variables.getUndeclaredTransient(uri);
+    for (const u of undeclaredTransient) {
+      diagnostics.push(makeDiag(
+        u.range,
+        DiagnosticCode.UndeclaredTransient,
+        `Transient variable '%${u.name}' is not declared in StoryTransients`
+      ));
+    }
   }
 }
 function validateLinks(text, passages, passageNames, diagnostics) {
@@ -2342,6 +2477,26 @@ function validateWidgetInvocations(macros, workspace, diagnostics) {
     }
   }
 }
+function validateLineLength(text, passages, maxLength, diagnostics) {
+  const excludedTags = /* @__PURE__ */ new Set(["script", "stylesheet"]);
+  const excludedPassages = new Set(passages.filter((p) => p.tags?.some((t) => excludedTags.has(t))).map((p) => p.name));
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^::\s+/.test(line)) continue;
+    if (/^\s*<[a-zA-Z]/.test(line)) continue;
+    if (line.length > maxLength) {
+      diagnostics.push(makeDiag(
+        {
+          start: { line: i, character: maxLength },
+          end: { line: i, character: line.length }
+        },
+        DiagnosticCode.LineTooLong,
+        `Line exceeds ${maxLength} characters (${line.length})`
+      ));
+    }
+  }
+}
 function makeDiag(range, code, message) {
   return {
     range,
@@ -2639,6 +2794,7 @@ function parseArgs(args2) {
     format: "pretty",
     severity: null,
     configPath: null,
+    maxLineLength: null,
     patterns: []
   };
   let i = 0;
@@ -2674,6 +2830,14 @@ function parseArgs(args2) {
     } else if (arg.startsWith("--config=")) {
       options.configPath = arg.slice("--config=".length);
       i++;
+    } else if (arg === "--max-line-length" && i + 1 < args2.length) {
+      const n = parseInt(args2[i + 1], 10);
+      if (!isNaN(n) && n > 0) options.maxLineLength = n;
+      i += 2;
+    } else if (arg.startsWith("--max-line-length=")) {
+      const n = parseInt(arg.slice("--max-line-length=".length), 10);
+      if (!isNaN(n) && n > 0) options.maxLineLength = n;
+      i++;
     } else if (!arg.startsWith("--")) {
       options.patterns.push(arg);
       i++;
@@ -2751,10 +2915,14 @@ async function runCheck(args2) {
   if (Object.keys(projectConfig.macros).length > 0) {
     workspace.macros.loadSupplements(projectConfig.macros);
   }
+  const diagOptions = {};
+  if (options.maxLineLength !== null) {
+    diagOptions.maxLineLength = options.maxLineLength;
+  }
   const allResults = [];
   let hasErrors = false;
   for (const uri of fileContents.keys()) {
-    let diags = computeDiagnostics(uri, workspace);
+    let diags = computeDiagnostics(uri, workspace, diagOptions);
     if (options.severity) {
       diags = filterBySeverity(diags, options.severity);
     }
@@ -3175,7 +3343,10 @@ async function formatDocument(text, options) {
         }
         continue;
       }
-      const indented = indentMacros(region.lines, isBlock, isDedenting);
+      let indented = indentMacros(region.lines, isBlock, isDedenting);
+      if (options?.maxLineLength) {
+        indented = wrapLines(indented, options.maxLineLength);
+      }
       resultLines.push(...indented);
     }
   }
@@ -3209,12 +3380,78 @@ function indentMacros(lines, isBlock, isDedenting) {
     if (openMatch && isBlock(openMatch[1])) {
       indentLevel++;
     }
+    const closeGlobal = /\{\/[A-Za-z][\w-]*\s*\}/g;
+    let cm;
+    while ((cm = closeGlobal.exec(trimmed)) !== null) {
+      if (cm.index > 0) {
+        indentLevel = Math.max(0, indentLevel - 1);
+      }
+    }
   }
   return result;
 }
 async function formatRange(text, _range, options) {
   return formatDocument(text, options);
 }
+function wrapLines(lines, maxLen) {
+  const result = [];
+  for (const line of lines) {
+    if (line.length <= maxLen) {
+      result.push(line);
+      continue;
+    }
+    const trimmed = line.trim();
+    if (trimmed === "" || /^::/.test(trimmed) || /^\{[\/#.]/.test(trimmed) || // closing/opening-only macro lines
+    /^\[\[/.test(trimmed) || // links
+    /^\{choice\b/.test(trimmed) || // choice macros
+    /^\{choices\b/.test(trimmed)) {
+      result.push(line);
+      continue;
+    }
+    const indentMatch = line.match(/^(\s*)/);
+    const indent = indentMatch ? indentMatch[1] : "";
+    const wrapped = wordWrap(trimmed, maxLen, indent);
+    result.push(...wrapped);
+  }
+  return result;
+}
+function wordWrap(text, maxLen, indent) {
+  const lines = [];
+  let remaining = text;
+  while (remaining.length > 0) {
+    const currentMax = lines.length === 0 ? maxLen - indent.length : maxLen - indent.length;
+    if (remaining.length <= currentMax) {
+      lines.push(indent + remaining);
+      break;
+    }
+    let breakIdx = -1;
+    let inMacro = 0;
+    for (let i = 0; i < remaining.length && i <= currentMax; i++) {
+      if (remaining[i] === "{") inMacro++;
+      else if (remaining[i] === "}") inMacro = Math.max(0, inMacro - 1);
+      else if (remaining[i] === " " && inMacro === 0 && i > 0) {
+        breakIdx = i;
+      }
+    }
+    if (breakIdx === -1) {
+      for (let i = currentMax + 1; i < remaining.length; i++) {
+        if (remaining[i] === "{") inMacro++;
+        else if (remaining[i] === "}") inMacro = Math.max(0, inMacro - 1);
+        else if (remaining[i] === " " && inMacro === 0) {
+          breakIdx = i;
+          break;
+        }
+      }
+    }
+    if (breakIdx === -1) {
+      lines.push(indent + remaining);
+      break;
+    }
+    lines.push(indent + remaining.substring(0, breakIdx));
+    remaining = remaining.substring(breakIdx + 1);
+  }
+  return lines;
+}
 function normalizePassageHeader(line) {
   const headerMatch = line.match(/^::\s+(.*)/);
   if (!headerMatch) return line;
@@ -3304,13 +3541,28 @@ import { glob as glob2 } from "glob";
 function parseArgs2(args2) {
   const options = {
     check: false,
+    maxLineLength: null,
     patterns: []
   };
-  for (const arg of args2) {
+  let i = 0;
+  while (i < args2.length) {
+    const arg = args2[i];
     if (arg === "--check") {
       options.check = true;
+      i++;
+    } else if (arg === "--max-line-length" && i + 1 < args2.length) {
+      const n = parseInt(args2[i + 1], 10);
+      if (!isNaN(n) && n > 0) options.maxLineLength = n;
+      i += 2;
+    } else if (arg.startsWith("--max-line-length=")) {
+      const n = parseInt(arg.slice("--max-line-length=".length), 10);
+      if (!isNaN(n) && n > 0) options.maxLineLength = n;
+      i++;
     } else if (!arg.startsWith("--")) {
       options.patterns.push(arg);
+      i++;
+    } else {
+      i++;
     }
   }
   if (options.patterns.length === 0) {
@@ -3335,11 +3587,15 @@ async function runFormat(args2) {
     console.log("No files found");
     return 0;
   }
+  const formatOpts = {};
+  if (options.maxLineLength !== null) {
+    formatOpts.maxLineLength = options.maxLineLength;
+  }
   const unformatted = [];
   for (const filePath of uniqueFiles) {
     try {
       const text = readFileSync5(filePath, "utf-8");
-      const formatted = await formatDocument(text);
+      const formatted = await formatDocument(text, formatOpts);
       if (formatted !== text) {
         if (options.check) {
           const relative = filePath.startsWith(cwd) ? filePath.slice(cwd.length + 1) : filePath;
@@ -3615,6 +3871,10 @@ function getCompletions(uri, position, triggerChar, workspace) {
   if (/\{\/[A-Za-z\w-]*$/.test(lineText)) {
     return getClosingMacroCompletions(text, position, workspace);
   }
+  const transientDotPathMatch = /%([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)?$/.exec(lineText);
+  if (transientDotPathMatch) {
+    return getTransientDotPathCompletions(transientDotPathMatch[1], workspace);
+  }
   const dotPathMatch = /\$([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)?$/.exec(lineText);
   if (dotPathMatch) {
     return getDotPathCompletions(dotPathMatch[1], workspace);
@@ -3628,6 +3888,9 @@ function getCompletions(uri, position, triggerChar, workspace) {
   if (/@[A-Za-z_$]?[\w$]*$/.test(lineText)) {
     return getLocalVariableCompletions(text);
   }
+  if (/%[A-Za-z_$]?[\w$]*$/.test(lineText) && !/%[A-Za-z_$][\w$]*\./.test(lineText)) {
+    return getTransientVariableCompletions(workspace);
+  }
   if (/\[\[[^\]]*$/.test(lineText)) {
     return getPassageNameCompletions(workspace);
   }
@@ -3755,6 +4018,33 @@ function getDotPathCompletions(varName, workspace) {
     detail: `field of $${varName}`
   }));
 }
+function getTransientVariableCompletions(workspace) {
+  const declared = workspace.variables.getDeclaredTransient();
+  if (declared.size === 0) return [];
+  const items = [];
+  for (const [name, decl] of declared) {
+    items.push({
+      label: `%${name}`,
+      kind: 6,
+      // CompletionItemKind.Variable
+      detail: "transient variable",
+      insertText: name,
+      documentation: decl.fields && decl.fields.length > 0 ? `Fields: ${decl.fields.join(", ")}` : void 0
+    });
+  }
+  return items;
+}
+function getTransientDotPathCompletions(varName, workspace) {
+  const declared = workspace.variables.getDeclaredTransient();
+  const decl = declared.get(varName);
+  if (!decl || !decl.fields || decl.fields.length === 0) return [];
+  return decl.fields.map((field) => ({
+    label: field,
+    kind: 5,
+    // CompletionItemKind.Field
+    detail: `field of %${varName}`
+  }));
+}
 function getPassageNameCompletions(workspace) {
   const passages = workspace.passages.getAllPassages();
   if (passages.length === 0) return [];
@@ -3774,7 +4064,7 @@ var init_completions = __esm({
       id: "completions",
       capabilities: {
         completionProvider: {
-          triggerCharacters: ["{", "$", "_", "@", "[", "."]
+          triggerCharacters: ["{", "$", "_", "@", "%", "[", "."]
         }
       },
       initialize(ctx) {
@@ -3898,6 +4188,28 @@ Fields: ${decl.fields.map((f) => `\`${f}\``).join(", ")}` : "";
       }
     }
   }
+  {
+    const re = /(?<!\w)%([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)/g;
+    let match;
+    while ((match = re.exec(line)) !== null) {
+      const start = match.index;
+      const end = start + match[0].length;
+      if (position.character >= start && position.character <= end) {
+        const baseName = match[1].split(".")[0];
+        const decl = workspace.variables.getDeclaredTransient().get(baseName);
+        const typeInfo = decl?.fields && decl.fields.length > 0 ? `
+
+Fields: ${decl.fields.map((f) => `\`${f}\``).join(", ")}` : "";
+        return {
+          contents: `**Transient variable** \`%${match[1]}\`${typeInfo}`,
+          range: {
+            start: { line: position.line, character: start },
+            end: { line: position.line, character: end }
+          }
+        };
+      }
+    }
+  }
   return null;
 }
 function getWidgetHover(line, position, workspace) {
@@ -4180,6 +4492,18 @@ function findReferences(uri, position, workspace, includeDeclaration) {
       }
     }
   }
+  {
+    const transRegex = /(?<!\w)%([A-Za-z_$][\w$]*)/g;
+    let match;
+    while ((match = transRegex.exec(line)) !== null) {
+      const start = match.index;
+      const end = start + match[0].length;
+      if (position.character >= start && position.character <= end) {
+        const varName = match[1];
+        return findTransientReferences(varName, workspace, includeDeclaration);
+      }
+    }
+  }
   {
     const widgetRegex = /\{([A-Za-z_$][\w$]*)/g;
     let match;
@@ -4274,6 +4598,20 @@ function findVariableReferences(varName, workspace, includeDeclaration) {
   }
   return locations;
 }
+function findTransientReferences(varName, workspace, includeDeclaration) {
+  const results = [];
+  if (includeDeclaration) {
+    const decl = workspace.variables.getDeclaredTransient().get(varName);
+    if (decl?.declarationUri && decl.declarationRange) {
+      results.push({ uri: decl.declarationUri, range: decl.declarationRange });
+    }
+  }
+  const usages = workspace.variables.getTransientUsages(varName);
+  for (const u of usages) {
+    results.push({ uri: u.uri, range: u.range });
+  }
+  return results;
+}
 function findWidgetReferences(widgetName, workspace, includeDeclaration) {
   const locations = [];
   if (includeDeclaration) {
@@ -4366,8 +4704,9 @@ function computeRename(uri, position, newName, workspace) {
       break;
     }
     case "variable": {
-      const bareName = newName.startsWith("$") ? newName.slice(1) : newName;
-      const refs = findVariableReferences(symbol.name, workspace, true);
+      const bareName = newName.startsWith("$") ? newName.slice(1) : newName.startsWith("%") ? newName.slice(1) : newName;
+      const isTransient = workspace.variables.getDeclaredTransient().has(symbol.name);
+      const refs = isTransient ? findTransientReferences(symbol.name, workspace, true) : findVariableReferences(symbol.name, workspace, true);
       for (const ref of refs) {
         addEdit(ref.uri, ref.range, bareName);
       }
@@ -4446,6 +4785,24 @@ function resolveSymbolAtCursor(uri, position, workspace) {
       }
     }
   }
+  {
+    const transRegex = /(?<!\w)%([A-Za-z_$][\w$]*)/g;
+    let match;
+    while ((match = transRegex.exec(line)) !== null) {
+      const start = match.index;
+      const end = start + match[0].length;
+      if (position.character >= start && position.character <= end) {
+        return {
+          kind: "variable",
+          name: match[1],
+          range: {
+            start: { line: position.line, character: start },
+            end: { line: position.line, character: end }
+          }
+        };
+      }
+    }
+  }
   {
     const widgetDefRegex2 = /\{widget\s+"([^"]+)"/gi;
     let match;
@@ -4643,6 +5000,7 @@ function computeInlayHints(uri, range, workspace) {
   const hints = [];
   addWidgetParamHints(text, range, workspace, hints);
   addVariableTypeHints(uri, text, range, workspace, hints);
+  addTransientTypeHints(uri, text, range, workspace, hints);
   return hints;
 }
 function addWidgetParamHints(text, range, workspace, hints) {
@@ -4699,6 +5057,28 @@ function addVariableTypeHints(uri, text, range, workspace, hints) {
     });
   }
 }
+function addTransientTypeHints(uri, text, range, workspace, hints) {
+  const storyTransientsPassage = workspace.passages.getStoryTransients();
+  if (!storyTransientsPassage) return;
+  if (storyTransientsPassage.uri !== uri) return;
+  const lines = text.split("\n");
+  const startLine = Math.max(range.start.line, 0);
+  const endLine = Math.min(range.end.line, lines.length - 1);
+  for (let lineNum = startLine; lineNum <= endLine; lineNum++) {
+    const line = lines[lineNum];
+    const declMatch = line.match(/^%([A-Za-z_$][\w$]*)\s*=\s*(.+)$/);
+    if (!declMatch) continue;
+    const valueStr = declMatch[2].trim();
+    const inferredType = inferType(valueStr);
+    if (!inferredType) continue;
+    const eqIdx = line.indexOf("=");
+    hints.push({
+      position: { line: lineNum, character: eqIdx },
+      label: `: ${inferredType}`,
+      kind: "type"
+    });
+  }
+}
 function inferType(value) {
   if (/^\d+(\.\d+)?$/.test(value)) return "number";
   if (/^"[^"]*"$/.test(value) || /^'[^']*'$/.test(value)) return "string";
@@ -4803,6 +5183,7 @@ function computeSemanticTokensAbsolute(uri, workspace) {
   const storyVarRegex = /(?<!\w)\$([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)/g;
   const tempVarRegex = /(?<!\w)_([A-Za-z_$][\w$]*)/g;
   const localVarRegex = /(?<!\w)@([A-Za-z_$][\w$]*)/g;
+  const transientVarRegex = /(?<!\w)%([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)/g;
   const sugarKeywordRegex = /\b(to|is|isnot|eq|neq|gt|gte|lt|lte|and|or|not|def|ndef)\b/g;
   for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
     if (headerLines.has(lineIndex)) continue;
@@ -4838,6 +5219,16 @@ function computeSemanticTokensAbsolute(uri, workspace) {
         tokenModifiers: encodeModifiers(["readonly"])
       });
     }
+    transientVarRegex.lastIndex = 0;
+    while ((m = transientVarRegex.exec(line)) !== null) {
+      tokens.push({
+        line: lineIndex,
+        startChar: m.index,
+        length: m[0].length,
+        tokenType: encodeType("variable"),
+        tokenModifiers: encodeModifiers(["defaultLibrary"])
+      });
+    }
     sugarKeywordRegex.lastIndex = 0;
     while ((m = sugarKeywordRegex.exec(line)) !== null) {
       tokens.push({
@@ -4942,6 +5333,11 @@ function computeCodeActions(uri, diagnostics, workspace) {
         if (action) actions.push(action);
         break;
       }
+      case DiagnosticCode.UndeclaredTransient: {
+        const action = fixUndeclaredTransient(diag, workspace);
+        if (action) actions.push(action);
+        break;
+      }
     }
   }
   return actions;
@@ -5024,6 +5420,40 @@ function fixNoStoryVariables(uri, workspace) {
     }]
   };
 }
+function fixUndeclaredTransient(diag, workspace) {
+  const match = diag.message.match(/'%(\w+)'/);
+  if (!match) return null;
+  const varName = match[1];
+  const storyTransients = workspace.passages.getStoryTransients();
+  if (!storyTransients) return null;
+  const storyTransientsUri = storyTransients.uri;
+  const text = workspace.documents.getText(storyTransientsUri);
+  if (text === void 0) return null;
+  const lines = text.split("\n");
+  const contentStart = storyTransients.headerEnd.end.line + 1;
+  let contentEnd = lines.length;
+  for (let i = contentStart; i < lines.length; i++) {
+    if (/^::\s+/.test(lines[i])) {
+      contentEnd = i;
+      break;
+    }
+  }
+  const insertLine = contentEnd;
+  return {
+    title: `Declare '%${varName}' in StoryTransients`,
+    kind: "quickfix",
+    diagnosticCodes: [DiagnosticCode.UndeclaredTransient],
+    edits: [{
+      uri: storyTransientsUri,
+      range: {
+        start: { line: insertLine, character: 0 },
+        end: { line: insertLine, character: 0 }
+      },
+      newText: `%${varName} = null
+`
+    }]
+  };
+}
 function toLspRange6(r) {
   return {
     start: { line: r.start.line, character: r.start.character },
@@ -5589,8 +6019,34 @@ var init_server2 = __esm({
 });
 
 // src/bin.ts
+import { createRequire as createRequire2 } from "node:module";
 var args = process.argv.slice(2);
-if (args[0] === "check") {
+var VERSION = createRequire2(import.meta.url)("../package.json").version;
+var HELP = `spindle-lsp v${VERSION}
+Language Server Protocol server for Spindle story format
+
+Usage:
+  spindle-lsp                Start the LSP server (stdio)
+  spindle-lsp check <files>  Lint .twee/.tw files
+  spindle-lsp format <files> Format .twee/.tw files in place
+  spindle-lsp mcp            Start the MCP server
+
+Options:
+  --help, -h                 Show this help message
+  --version, -v              Show version number
+
+Check options:
+  --format <pretty|json|sarif>   Output format (default: pretty)
+  --severity <level>             Minimum severity: error, warning, info, hint
+  --config <path>                Path to config file
+  --max-line-length <n>          Warn on lines exceeding n characters`;
+if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+  console.log(HELP);
+  process.exit(0);
+} else if (args.includes("--version") || args.includes("-v")) {
+  console.log(VERSION);
+  process.exit(0);
+} else if (args[0] === "check") {
   const { runCheck: runCheck2 } = await Promise.resolve().then(() => (init_check(), check_exports));
   const exitCode = await runCheck2(args.slice(1));
   process.exit(exitCode);