@cratis/screenplay-language 4.47.0 → 4.48.0

package/file-imports.ts

@@ -0,0 +1,70 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { fenceMap, indentOf } from './document-context';
+
+// An `import "<path or glob>"` of other .play files, with the pattern exactly as written and the span it
+// occupies between the quotes. Columns are one-based like every other position this package reports.
+export interface FileImport {
+    pattern: string;
+    line: number;
+    startColumn: number;
+    endColumn: number;
+}
+
+// The compiler's own shape for a file import (FileImportParser): a quoted operand without quotes or escapes.
+const fileImportPattern = /^import(\s+)"([^"\\]+)"\s*(?:\/\/.*)?$/;
+const quotedImportPattern = /^import\s+"/;
+
+// Whether a line imports files rather than a qualified name - its operand is quoted.
+export function isFileImportLine(line: string): boolean {
+    return quotedImportPattern.test(line.trim());
+}
+
+// The file import on a single line, or undefined when the line is not a well-formed one.
+export function fileImportOn(line: string, lineIndex: number): FileImport | undefined {
+    const indent = indentOf(line);
+    const match = line.slice(indent).match(fileImportPattern);
+    if (!match) return undefined;
+    const startColumn = indent + 'import'.length + match[1].length + 2;
+    return { pattern: match[2], line: lineIndex, startColumn, endColumn: startColumn + match[2].length };
+}
+
+// Every well-formed file import in a document, in document order, skipping code fences.
+export function fileImports(lines: string[]): FileImport[] {
+    const fences = fenceMap(lines);
+    const found: FileImport[] = [];
+    for (let index = 0; index < lines.length; index++) {
+        if (fences[index]) continue;
+        const fileImport = fileImportOn(lines[index], index);
+        if (fileImport) found.push(fileImport);
+    }
+    return found;
+}
+
+const folderOf = (path: string): string[] => path.split('/').slice(0, -1);
+
+function relativeTo(from: readonly string[], path: string): string {
+    const segments = path.split('/');
+    let common = 0;
+    while (common < from.length && common < segments.length - 1 && from[common] === segments[common]) common++;
+    return [...from.slice(common).map(() => '..'), ...segments.slice(common)].join('/');
+}
+
+// What an import written in a document can name: every other .play file, relative to the document's folder;
+// a glob for the files directly in each folder holding one; and a glob for everything beneath each folder on
+// the way to them. Paths are portable ('/' separated) and relative to one root, the way the compiler resolves them.
+export function importablePaths(documentPath: string, files: readonly string[]): string[] {
+    const from = folderOf(documentPath);
+    const paths = new Set<string>();
+    for (const file of files.filter((candidate) => candidate !== documentPath && candidate.toLowerCase().endsWith('.play'))) {
+        const relative = relativeTo(from, file);
+        const folders = folderOf(relative);
+        paths.add(relative);
+        paths.add([...folders, '*.play'].join('/'));
+        for (let depth = 0; depth <= folders.length; depth++) {
+            paths.add([...folders.slice(0, depth), '**', '*.play'].join('/'));
+        }
+    }
+    return [...paths].sort();
+}

package/for_fileImports/when_finding_file_imports.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { FileImport, fileImportOn, fileImports, isFileImportLine } from '../file-imports';
+
+describe('when finding file imports', () => {
+    let found: FileImport[];
+
+    beforeEach(() => {
+        found = fileImports([
+            'import Customers.CustomerRegistered',
+            'import "**/*.play"',
+            'module Ordering',
+            '  import   "Orders/*.play" // the orders',
+            '  screen Overview',
+            '    ```typescript',
+            'import "not/a/play/import"',
+            '    ```',
+        ]);
+    });
+
+    it('should find the quoted imports outside code fences', () => {
+        found.map((each) => each.pattern).should.deep.equal(['**/*.play', 'Orders/*.play']);
+    });
+
+    it('should locate the pattern between the quotes', () => {
+        found[1].should.deep.equal({ pattern: 'Orders/*.play', line: 3, startColumn: 13, endColumn: 26 });
+    });
+
+    it('should not read a malformed import as one', () => {
+        (fileImportOn('import "a\\b.play"', 0) === undefined).should.be.true;
+    });
+
+    it('should tell a file import from a qualified one by its quote', () => {
+        [isFileImportLine('  import "x'), isFileImportLine('import X.Y')].should.deep.equal([true, false]);
+    });
+});

package/for_importablePaths/when_listing_what_a_document_can_import.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { importablePaths } from '../file-imports';
+
+describe('when listing what a document can import', () => {
+    let paths: string[];
+
+    beforeEach(() => {
+        paths = importablePaths('Ordering/Ordering.play', [
+            'application.play',
+            'Ordering/Ordering.play',
+            'Ordering/Orders/PlaceOrder.play',
+            'Ordering/notes.md',
+            'Shared/Concepts.play',
+        ]);
+    });
+
+    it('should name every other play file relative to the document, with globs for the folders on the way', () => {
+        paths.should.deep.equal([
+            '**/*.play',
+            '../**/*.play',
+            '../*.play',
+            '../Shared/**/*.play',
+            '../Shared/*.play',
+            '../Shared/Concepts.play',
+            '../application.play',
+            'Orders/**/*.play',
+            'Orders/*.play',
+            'Orders/PlaceOrder.play',
+        ]);
+    });
+});

package/for_planCompletions/when_completing_a_file_import.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, it } from 'vitest';
+import { completionEntriesFor, planCompletions } from '../completion-planner';
+import { hoverContent } from '../hover-content';
+
+describe('when completing a file import', () => {
+    it('should complete a path inside the quotes, replacing what is typed', () => {
+        planCompletions(['module Ordering', '  import "Ord'], 1, '  import "Ord').should.deep.equal({ kind: 'playFiles', replaceLength: 3 });
+    });
+
+    it('should offer nothing after a quote outside an import', () => {
+        planCompletions(['module Ordering', '  description "'], 1, '  description "').should.deep.equal({ kind: 'none' });
+    });
+
+    for (const [chain, scope] of [[[], 'top level'], [['module'], 'module'], [['feature', 'module'], 'feature']] as const) {
+        it(`should offer a file import at the ${scope}`, () => {
+            completionEntriesFor([...chain]).some((entry) => entry.label === 'import "…"').should.be.true;
+        });
+    }
+
+    it('should document both kinds of import on hover', () => {
+        hoverContent(['import "**/*.play"'], 0, 'import', 1, 7)!.should.contain('places the imported files there');
+    });
+});

package/for_planCompletions/when_completing_a_specification_step.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, it } from 'vitest';
+import { completionEntriesFor, planCompletions } from '../completion-planner';
+import { hoverContent } from '../hover-content';
+
+const specification = ['slice StateView Hours', '  specification AtOpening'];
+const labelsAfter = (textBefore: string): string[] => {
+    const plan = planCompletions([...specification, textBefore], 2, textBefore);
+    return plan.kind === 'entries' ? plan.entries.map((entry) => entry.label) : [plan.kind];
+};
+
+describe('when completing a specification step', () => {
+    it('should offer what can follow given', () => {
+        labelsAfter('    given ').should.include.members(['clock', 'capture']);
+    });
+
+    it('should offer what can follow when', () => {
+        labelsAfter('    when ').should.include.members(['clock', 'trigger', 'capture', 'query']);
+    });
+
+    it('should offer what can follow then', () => {
+        labelsAfter('    then res').should.include.members(['result', 'result exactly', 'no result']);
+    });
+
+    it('should offer the queries after when query', () => {
+        labelsAfter('    when query Opening').should.deep.equal(['queries']);
+    });
+
+    it('should offer every step on an empty line', () => {
+        completionEntriesFor(['specification']).map((entry) => entry.label).should.include.members(['given clock', 'when trigger', 'when capture', 'when query', 'then result', 'then no result']);
+    });
+
+    it('should document a step word in a specification', () => {
+        hoverContent([...specification, '    when trigger NightlySync'], 2, 'trigger', 10, 17)!.should.contain('application trigger fires');
+    });
+
+    it('should document a step word not in a specification as the keyword', () => {
+        hoverContent(['trigger NightlySync'], 0, 'trigger', 1, 8)!.should.not.contain('application trigger fires');
+    });
+});

package/for_tokens/when_highlighting_a_file_import.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, it } from 'vitest';
+import { createTokensProvider } from '../tokens';
+
+const rules = createTokensProvider([]).tokenizer.root as unknown as [RegExp, unknown][];
+const fileImportRule = rules.find((rule) => Array.isArray(rule[1]) && (rule[1] as string[]).includes('string.link'));
+
+describe('when highlighting a file import', () => {
+    it('should read the quoted path as a link', () => {
+        fileImportRule![0].test('  import "Orders/**/*.play"').should.be.true;
+    });
+
+    it('should leave a qualified import to the keyword rules', () => {
+        fileImportRule![0].test('import Customers.CustomerRegistered').should.be.false;
+    });
+});

package/for_tokens/when_highlighting_specification_steps.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, it } from 'vitest';
+import { ensureBuiltInSubLanguages } from '../index';
+import { getSubLanguages } from '../sub-language-registry';
+import { createTokensProvider } from '../tokens';
+
+ensureBuiltInSubLanguages();
+const rules = createTokensProvider(getSubLanguages()).tokenizer.root as unknown as [RegExp, unknown][];
+const stepRules = rules.filter((rule) => Array.isArray(rule[1]) && (rule[1] as string[]).join() === 'white,keyword,white,keyword');
+const captureLanguage = rules.findIndex((rule) => rule[0].source === '\\bcapture\\b');
+
+describe('when highlighting specification steps', () => {
+    it('should come before the capture sub-language can claim a step', () => {
+        rules.indexOf(stepRules[stepRules.length - 1]).should.be.below(captureLanguage);
+    });
+
+    for (const line of ['    given clock "2026-10-05T08:00:00Z"', '    given capture LegacyLoans', '    when trigger NightlySync', '    when query OpeningHoursFor', '    then result exactly', '    then no result']) {
+        it(`should read the step words of '${line.trim()}' as keywords`, () => {
+            stepRules.some((rule) => rule[0].test(line)).should.be.true;
+        });
+    }
+
+    it('should leave a capture declaration to the sub-language', () => {
+        stepRules.some((rule) => rule[0].test('      capture LegacyLoans')).should.be.false;
+    });
+});

package/for_validateLines/when_validating_a_document/with_a_problem_of_every_coded_kind.ts

@@ -13,6 +13,7 @@ const document = [
     'concept Amount : Wat',
     '',
     'module Invoicing',
+    '  import Customers.CustomerRegistered',
     '  feature Invoices',
     '    slice Wat Register',
     '      event InvoiceRegistered',

package/for_validateLines/when_validating_a_file_placed_by_an_import/with_names_declared_in_other_files.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { mergeSymbols, scanDocument } from '../../symbols';
+import { ValidationIssue, validateLines } from '../../validation';
+
+// A file an import places in a feature holds slices at its top level, and the names it uses are declared in
+// the other files of the application.
+describe('when validating a file placed by an import with names declared in other files', () => {
+    let issues: ValidationIssue[];
+    let alone: ValidationIssue[];
+    const fragment = [
+        'slice StateChange PlaceOrder',
+        '  command PlaceOrder',
+        '    orderId OrderId identifier',
+        '    customer Customer',
+        '    authorize Staff',
+        '    produces OrderPlaced',
+        '      for orderId',
+        '  reaction Notify',
+        '    when OrderPlaced',
+        '      produces CustomerNotified',
+    ];
+
+    beforeEach(() => {
+        const application = mergeSymbols(
+            scanDocument(['concept OrderId : Uuid', 'policy Staff', '  require authenticated']),
+            scanDocument(['type Customer', '  name String', 'module Ordering', '  feature Orders', '    slice StateChange PlaceOrder', '      event OrderPlaced', '        note String']),
+            scanDocument(['import Customers.CustomerNotified']),
+        );
+        issues = validateLines(fragment, { application });
+        alone = validateLines(fragment);
+    });
+
+    it('should report nothing', () => {
+        issues.should.be.empty;
+    });
+
+    it('should report the names as unknown without the application', () => {
+        alone.map((issue) => issue.code).should.deep.equal(['PLAY0165', 'PLAY0165', 'PLAY0167', 'PLAY0166', 'PLAY0166']);
+    });
+});

package/for_validateLines/when_validating_file_imports/at_every_level.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { diagnosticCodes } from '../../diagnostic-codes';
+import { ValidationIssue, validateLines } from '../../validation';
+
+describe('when validating file imports at every level', () => {
+    let issues: ValidationIssue[];
+
+    beforeEach(() => {
+        issues = validateLines([
+            'import Customers.CustomerRegistered',
+            'import "**/*.play" // every document',
+            'import "Bad\\Path.play"',
+            'module Ordering',
+            '  import "Orders/*.play"',
+            '  import Customers.CustomerRegistered',
+            '  feature Orders',
+            '    import "Slices/**/*.play"',
+            '    import "Unclosed',
+        ]);
+    });
+
+    it('should report the malformed and the qualified imports inside a body', () => {
+        issues.map((issue) => `${issue.code}@${issue.line}`).should.deep.equal([
+            `${diagnosticCodes.invalidFileImport}@2`,
+            `${diagnosticCodes.invalidFileImport}@5`,
+            `${diagnosticCodes.invalidFileImport}@8`,
+        ]);
+    });
+
+    it('should span the whole import', () => {
+        issues[1].should.include({ startColumn: 3, endColumn: 3 + 'import Customers.CustomerRegistered'.length });
+    });
+});

package/hover-content.ts

@@ -4,7 +4,7 @@
 import { enclosingChain, fenceMap, indentOf } from './document-context';
 import { scanDocument } from './symbols';
 import { getSubLanguage } from './sub-language-registry';
-import { attributeDocs, contextVariableDocs, keywordDocs } from './keyword-docs';
+import { attributeDocs, contextVariableDocs, keywordDocs, specificationKeywordDocs } from './keyword-docs';
 
 // Produces the hover markdown for a word at a position, without any editor
 // dependency — the Monaco service and the VSCode extension share this content.
@@ -97,6 +97,11 @@ export function hoverContent(
         return '**reads** — Declares a whole view this clock trigger consults: `reads <View>`. Clock triggers take no values, so `by` is unavailable.';
     }
 
+    const step = line.trim().match(/^(given|when|then)\s+(?:no\s+)?(\w+)/);
+    if (step && step[2] === word && chain[0] === 'specification' && specificationKeywordDocs[word]) {
+        return `**${word}** — ${specificationKeywordDocs[word]}`;
+    }
+
     const keywordDoc = keywordDocs[word];
     if (keywordDoc) return `**${word}** — ${keywordDoc}`;
 

package/index.ts

@@ -8,7 +8,7 @@ import {
     languageId,
 } from './language';
 import { createTokensProvider } from './tokens';
-import { createCompletionProvider } from './completions';
+import { CompletionOptions, createCompletionProvider } from './completions';
 import { createHoverProvider } from './hover';
 import { attachDiagnostics } from './diagnostics';
 import {
@@ -38,7 +38,10 @@ export function ensureBuiltInSubLanguages(): void {
     if (!getSubLanguage('capture')) registerSubLanguage('capture', cdl);
 }
 
-export function register(monaco: Monaco): void {
+// What a host can tell the language service beyond the models it holds.
+export type LanguageServiceOptions = CompletionOptions;
+
+export function register(monaco: Monaco, options: LanguageServiceOptions = {}): void {
     if (registeredInstances.has(monaco)) return;
 
     ensureBuiltInSubLanguages();
@@ -48,7 +51,7 @@ export function register(monaco: Monaco): void {
     monaco.languages.register(languageExtensionPoint);
     monaco.languages.setLanguageConfiguration(languageId, languageConfiguration);
     applyTokensProvider(monaco);
-    monaco.languages.registerCompletionItemProvider(languageId, createCompletionProvider(monaco));
+    monaco.languages.registerCompletionItemProvider(languageId, createCompletionProvider(monaco, options));
     monaco.languages.registerHoverProvider(languageId, createHoverProvider());
     monaco.editor.defineTheme(screenplayDarkThemeName, screenplayDark);
     monaco.editor.defineTheme(screenplayLightThemeName, screenplayLight);
@@ -86,7 +89,10 @@ export {
     isAbsoluteFileReferencePath,
 } from './file-references';
 export type { FileReference } from './file-references';
-export { builtInTriggerNames, knownEventNames, knownTriggerNames, knownTypeNames, scanDocument } from './symbols';
+export { fileImportOn, fileImports, importablePaths, isFileImportLine } from './file-imports';
+export type { FileImport } from './file-imports';
+export type { CompletionOptions } from './completions';
+export { builtInTriggerNames, knownEventNames, knownTriggerNames, knownTypeNames, mergeSymbols, scanDocument } from './symbols';
 export type {
     CommandSymbol,
     ConceptSymbol,
@@ -100,15 +106,15 @@ export type {
     QuerySymbol,
     TypeSymbol,
 } from './symbols';
-export { attributeDocs, contextVariableDocs, keywordDocs } from './keyword-docs';
+export { attributeDocs, contextVariableDocs, keywordDocs, specificationKeywordDocs } from './keyword-docs';
 export { eventContextMemberAt, eventContextMembers, eventContextMembersAfter, eventContextPaths, namesEventContextMember } from './event-context';
 export type { EventContextMember, EventContextPath } from './event-context';
-export { contextVariableItems, producesItems } from './completion-items';
+export { contextVariableItems, producesItems, specificationStepItems } from './completion-items';
 export type { CompletionEntry } from './completion-items';
 export { completionEntriesFor, planCompletions } from './completion-planner';
 export type { CompletionPlan } from './completion-planner';
 export { hoverContent } from './hover-content';
 export { validateLines } from './validation';
-export type { ValidationIssue, ValidationSeverity } from './validation';
+export type { ValidationContext, ValidationIssue, ValidationSeverity } from './validation';
 export { diagnosticCodes } from './diagnostic-codes';
 export type { DiagnosticCode } from './diagnostic-codes';

package/keyword-docs.ts

@@ -5,7 +5,7 @@ import { eventContextPaths } from './event-context';
 
 export const keywordDocs: Record<string, string> = {
     domain: 'The domain the file belongs to — optional, at most one per file, before everything else.',
-    import: 'Imports a type from another module; it becomes available by its short name.',
+    import: 'Imports a type from another module by its qualified name — `import Module.Type` — making it available by its short name; or, quoted, other `.play` files by path or glob — `import "Orders/**/*.play"`, relative to this file\'s folder. Written inside a module or feature, a file import places the imported files there: their top level is that module\'s or feature\'s body.',
     concept: 'A formalized value type wrapping a primitive. Attributes such as `@pii` travel with every usage, optionally with a `<attribute> reason "..."` line saying why.',
     type: 'A composite value type — a named shape built from several properties, referenced by events, commands and other types the same way a concept is.',
     reason: 'Records why a concept attribute applies — the purpose, the lawful basis, whose subject the value lives under. Written as `pii reason "..."` in the concept body.',
@@ -71,7 +71,9 @@ export const keywordDocs: Record<string, string> = {
     readmodel: 'Read model state in a specification — `given readmodel` establishes it, `then readmodel` asserts it, `then no readmodel <View> for <key>` asserts keyed absence.',
     no: 'A keyed absence assertion: `then no readmodel <View> for <key>`.',
     arguments: 'The values supplied to a query asserted by `then query`.',
-    result: 'One expected result of a `then query` assertion. Repeat it to assert several results in authored order.',
+    result: 'One expected result - `then result [exactly]` after `when query`, or a `result` block inside `then query`. Repeat it to assert several results in authored order.',
+    clock: 'The instant a specification happens at - `given clock "2026-10-05T08:00:00Z"` fixes when everything occurs; `when clock "<instant>"` is the clock reaching it, as the action.',
+    exactly: 'Requires every property to match, rather than only the ones asserted - on `then readmodel`, `then query` and `then result`.',
     file: 'Delegates the implementation to an external file; the Screenplay contract stays visible.',
     by: 'Introduces the identifying parameter.',
     via: 'Connects screen data to the query that supplies it.',
@@ -107,6 +109,16 @@ export const keywordDocs: Record<string, string> = {
     Enum: 'An enumeration concept with a fixed set of values.',
 };
 
+// What the words of a specification's steps mean there - where 'trigger', 'capture' and 'query' name what the
+// scenario exercises rather than declare one.
+export const specificationKeywordDocs: Record<string, string> = {
+    clock: keywordDocs.clock,
+    trigger: '`when trigger <Trigger>` - an application trigger fires, as the action, with the values on the lines beneath it.',
+    capture: '`given capture <Capture>` - a record the capture\'s source held before; `when capture <Capture>` - the record it sees now, as the action. The fields go on the lines beneath.',
+    query: '`when query <Query>` - the query is performed, as the action, with its arguments on the lines beneath; assert what it returns with `then result` or `then no result`. `then query` instead asserts a query after another action.',
+    result: '`then result [exactly]` - one result the query performed by `when query` returns, in order; `then no result` - it returns nothing.',
+};
+
 export const attributeDocs: Record<string, string> = {
     pii: '`@pii` — the value is personally identifiable information; Chronicle manages and erases it automatically wherever the concept is used. Add `pii reason "..."` in the concept body to record why.',
     sensitive: '`@sensitive` — the value is sensitive; Chronicle applies its sensitivity rules automatically wherever the concept is used. Add `sensitive reason "..."` in the concept body to record why.',

package/language.ts

@@ -75,6 +75,8 @@ export const clauseKeywords = [
     'then',
     'arguments',
     'result',
+    'clock', // A specification step - 'given clock' and 'when clock' state an instant.
+    'exactly',
     'error',
     'message',
     'not',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/screenplay-language",
-    "version": "4.47.0",
+    "version": "4.48.0",
     "description": "Monaco language service for the Cratis Screenplay DSL — syntax highlighting, IntelliSense, hover and diagnostics for .play files",
     "keywords": [
         "cratis",

package/symbols.ts

@@ -266,6 +266,22 @@ export function scanDocument(lines: string[]): DocumentSymbols {
     return symbols;
 }
 
+// The symbols of several documents as one - what an application spread over files declares. Lines refer to
+// the document each symbol came from, so the result names things; it does not locate them.
+export function mergeSymbols(...documents: DocumentSymbols[]): DocumentSymbols {
+    return {
+        imports: documents.flatMap((document) => document.imports),
+        concepts: documents.flatMap((document) => document.concepts),
+        types: documents.flatMap((document) => document.types),
+        policies: documents.flatMap((document) => document.policies),
+        events: documents.flatMap((document) => document.events),
+        commands: documents.flatMap((document) => document.commands),
+        queries: documents.flatMap((document) => document.queries),
+        screens: documents.flatMap((document) => document.screens),
+        triggers: documents.flatMap((document) => document.triggers),
+    };
+}
+
 export function knownEventNames(symbols: DocumentSymbols): string[] {
     return [
         ...symbols.events.map((event) => event.name),

package/themes/screenplay-dark.ts

@@ -18,6 +18,7 @@ export const screenplayDark: editor.IStandaloneThemeData = {
         { token: 'annotation.play', foreground: 'DCDCAA' },
         { token: 'variable.predefined.play', foreground: 'D7BA7D' },
         { token: 'string.play', foreground: 'CE9178' },
+        { token: 'string.link.play', foreground: 'CE9178', fontStyle: 'underline' },
         { token: 'string.invalid.play', foreground: 'F44747' },
         { token: 'string.quote.play', foreground: '6A9955' },
         { token: 'number.play', foreground: 'B5CEA8' },

package/themes/screenplay-light.ts

@@ -18,6 +18,7 @@ export const screenplayLight: editor.IStandaloneThemeData = {
         { token: 'annotation.play', foreground: '795E26' },
         { token: 'variable.predefined.play', foreground: 'B45309' },
         { token: 'string.play', foreground: 'A31515' },
+        { token: 'string.link.play', foreground: 'A31515', fontStyle: 'underline' },
         { token: 'string.invalid.play', foreground: 'CD3131' },
         { token: 'string.quote.play', foreground: '008000' },
         { token: 'number.play', foreground: '098658' },

package/tokens.ts

@@ -53,6 +53,12 @@ export const commonTokenRules: MonarchTokenRules = [
 export function createTokensProvider(subLanguages: SubLanguage[]): languages.IMonarchLanguage {
     const tokenizer: Record<string, MonarchTokenRules> = {
         root: [
+            // A specification's clock, trigger, capture and query steps - matched before a sub-language keyword
+            // can claim 'capture' and read the rest of the specification as change data capture.
+            [/^(\s*)(given|when)(\s+)(clock|capture|trigger|query)\b/, ['white', 'keyword', 'white', 'keyword']],
+            [/^(\s*)(then)(\s+)(result|no\s+result)\b/, ['white', 'keyword', 'white', 'keyword']],
+            // A quoted import names .play files rather than a qualified name - the path reads as a link.
+            [/^(\s*)(import)(\s+)("[^"\\]*")/, ['white', 'keyword', 'white', 'string.link']],
             // Only an event header reserves 'generation'; properties and context paths do not.
             [/^(\s*)(event)(\s+)([A-Za-z_]\w*)(\s+)(generation)(?=\s+\d+\s*$)/,
                 ['white', 'keyword', 'white', 'type.identifier', 'white', 'keyword']],