@patterkit/compiler 0.2.8 → 0.4.0

package/dist/index.cjs

@@ -20,9 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  EXTERNAL_SCOPES: () => import_dialect4.EXTERNAL_SCOPES,
+  PATTER_SCOPE: () => PATTER_SCOPE,
   compileExpression: () => compileExpression,
   exportBundle: () => exportBundle,
-  hostScopesToSpec: () => import_dialect3.hostScopesToSpec,
+  externalGameScopes: () => externalGameScopes,
+  hostScopesToSpec: () => import_dialect4.hostScopesToSpec,
+  projectScopes: () => projectScopes,
   validateConditions: () => validateConditions,
   validateInterpolation: () => validateInterpolation
 });
@@ -30,15 +34,103 @@ module.exports = __toCommonJS(index_exports);
 
 // src/expressions.ts
 var import_expr = require("@wildwinter/expr");
+var import_dialect2 = require("@patterkit/dialect");
+var import_scopes2 = require("@wildwinter/scoperegistry/scopes");
+
+// src/game-scopes.ts
+var import_scopes = require("@wildwinter/scoperegistry/scopes");
 var import_dialect = require("@patterkit/dialect");
+var PATTER_SCOPE = "patter";
+function asHostScope(s) {
+  return {
+    token: s.token,
+    ...s.writable !== void 0 ? { writable: s.writable } : {},
+    ...s.declarations ? { declarations: s.declarations.map((d) => ({ ...d })) } : {}
+  };
+}
+function sameScope(a, b) {
+  const norm = (s) => JSON.stringify((0, import_dialect.hostScopesToSpec)({ version: 1, scopes: [s] }));
+  return norm(a) === norm(b);
+}
+function projectScopes(project, merged) {
+  const own = project.scopeRegistry;
+  if (!merged) return { host: own, external: [], notes: [] };
+  const notes = [];
+  const hosted = [];
+  const bundled = /* @__PURE__ */ new Set();
+  let changed = false;
+  const shared = (token) => token === PATTER_SCOPE ? void 0 : merged.spec.scopes.find((s) => s.token === token);
+  for (const h of own?.scopes ?? []) {
+    const s = shared(h.token);
+    const who = merged.owners.get(h.token);
+    if (!s || !who) {
+      hosted.push(h);
+      bundled.add(h.token);
+      continue;
+    }
+    if (who.fileName === import_scopes.GAME_SCOPES_FILE) {
+      const fromFile = asHostScope(s);
+      hosted.push(fromFile);
+      bundled.add(h.token);
+      changed = true;
+      if (!sameScope(h, fromFile)) {
+        notes.push({
+          token: h.token,
+          file: who.fileName,
+          message: `@${h.token} in World properties differs from ${import_scopes.GAME_SCOPES_DIR}/${who.fileName}, and the shared file wins: saving Project Settings in Patterpad brings the project's copy up to date`
+        });
+      }
+    } else {
+      changed = true;
+      notes.push({
+        token: h.token,
+        file: who.fileName,
+        message: `@${h.token} is declared in ${import_scopes.GAME_SCOPES_DIR}/${who.fileName}; remove it from World properties`
+      });
+    }
+  }
+  const world = shared("world");
+  if (world && merged.owners.get("world")?.fileName === import_scopes.GAME_SCOPES_FILE && !bundled.has("world")) {
+    hosted.push(asHostScope(world));
+    bundled.add("world");
+    changed = true;
+  }
+  const external = merged.spec.scopes.filter((s) => s.token !== PATTER_SCOPE && !bundled.has(s.token));
+  const host = !changed ? own : hosted.length ? { version: own?.version ?? 1, scopes: hosted } : void 0;
+  return { host, external, notes };
+}
+function externalGameScopes(strict, merged) {
+  if (!merged) return [];
+  const hostTokens = new Set((strict?.scopes ?? []).map((s) => s.token));
+  return merged.spec.scopes.filter((s) => s.token !== PATTER_SCOPE && !hostTokens.has(s.token));
+}
+
+// src/expressions.ts
 var import_model = require("@patterkit/model");
 function compileExpression(src, foreign) {
-  return (0, import_expr.compile)(src, (0, import_dialect.dialectWithForeignScopes)(foreign));
+  return (0, import_expr.compile)(src, (0, import_dialect2.dialectWithForeignScopes)(foreign));
+}
+function validationScopes(project, options) {
+  const merged = options.gameScopes;
+  const strict = options.foreignScopes ?? (merged ? (0, import_dialect2.hostScopesToSpec)(projectScopes(project, merged).host) : void 0);
+  const external = externalGameScopes(strict, merged);
+  const base = strict?.scopes ?? [];
+  const foreign = (0, import_dialect2.withEngineScopes)({ version: strict?.version ?? 1, scopes: [...base, ...external.map((s) => ({ token: s.token }))] });
+  const checked = external.some((s) => s.declarations?.length) ? (0, import_dialect2.withEngineScopes)({ version: strict?.version ?? 1, scopes: [...base, ...external] }) : void 0;
+  return { foreign, checked, external: new Set(external.map((s) => s.token)), merged };
+}
+var issueKey = (i) => `${i.kind}|${JSON.stringify(i.path)}|${i.message}`;
+function externalMessage(i, merged) {
+  if (merged && i.kind === "unresolved-scoped-property" && i.reference) {
+    const [token, name] = i.reference.split(".");
+    if (token && name) return (0, import_scopes2.referenceNote)(merged, token, name) ?? i.message;
+  }
+  return i.message;
 }
 function validateConditions(input, options = {}) {
   const issues = [];
-  const foreign = options.foreignScopes;
-  const dialect = (0, import_dialect.dialectWithForeignScopes)(foreign);
+  const { foreign, checked, external, merged } = validationScopes(input.project, options);
+  const dialect = (0, import_dialect2.dialectWithForeignScopes)(foreign);
   const readOnly = readOnlyForeignTargets(foreign);
   const opaqueForeign = opaqueForeignTokens(foreign);
   const isScopeToken = scopeTokenTest(foreign);
@@ -60,7 +152,8 @@ function validateConditions(input, options = {}) {
     }
   };
   const validateElement = (blocks, sceneProps, onEntry, elementId) => {
-    const schema = (0, import_dialect.buildSchema)(input.project, sceneProps, foreign);
+    const schema = (0, import_dialect2.buildSchema)(input.project, sceneProps, foreign);
+    const checkedSchema = checked ? (0, import_dialect2.buildSchema)(input.project, sceneProps, checked) : void 0;
     const check = (nodeId, field, src) => {
       let ast;
       try {
@@ -69,9 +162,16 @@ function validateConditions(input, options = {}) {
         issues.push({ nodeId, field, src, severity: "error", message: e instanceof Error ? e.message : String(e) });
         return;
       }
-      for (const iss of (0, import_expr.validateExpr)(ast, schema, dialect)) {
+      const strict = (0, import_expr.validateExpr)(ast, schema, dialect);
+      for (const iss of strict) {
         issues.push({ nodeId, field, src, severity: iss.severity, message: iss.message });
       }
+      if (checkedSchema) {
+        const seen = new Set(strict.map(issueKey));
+        for (const iss of (0, import_expr.validateExpr)(ast, checkedSchema, dialect)) {
+          if (!seen.has(issueKey(iss))) issues.push({ nodeId, field, src, severity: "warning", message: externalMessage(iss, merged) });
+        }
+      }
       checkVisitIds(ast, nodeId, field, src);
     };
     const checkTarget = (nodeId, field, target) => {
@@ -95,7 +195,12 @@ function validateConditions(input, options = {}) {
         });
         return;
       }
-      const { scope, name } = (0, import_dialect.splitRef)(target, isScopeToken);
+      const { scope, name } = (0, import_dialect2.splitRef)(target, isScopeToken);
+      if (external.has(scope)) {
+        const note = merged ? (0, import_scopes2.referenceNote)(merged, scope, name, { write: true }) : void 0;
+        if (note) issues.push({ nodeId, field, src: target, severity: "warning", message: note });
+        return;
+      }
       if (opaqueForeign.has(scope)) return;
       if (!schema.properties.get(scope)?.has(name)) {
         issues.push({
@@ -132,12 +237,14 @@ function validateInterpolation(input, options = {}) {
   const voiced = input.project.voiced ?? false;
   const tables = (input.locales ?? []).map((l) => ({ locale: l.locale, strings: l.strings }));
   const defaultLocale = input.project.locales.default;
-  const opaqueForeign = opaqueForeignTokens(options.foreignScopes);
-  const isScopeToken = scopeTokenTest(options.foreignScopes);
+  const { foreign, external, merged } = validationScopes(input.project, options);
+  const opaqueForeign = opaqueForeignTokens(foreign);
+  const isScopeToken = scopeTokenTest(foreign);
   for (const scene of input.scenes) {
-    const schema = (0, import_dialect.buildSchema)(input.project, scene.sceneProps, options.foreignScopes);
+    const schema = (0, import_dialect2.buildSchema)(input.project, scene.sceneProps, foreign);
     const known = (ref) => {
-      const { scope, name } = (0, import_dialect.splitRef)(ref, isScopeToken);
+      const { scope, name } = (0, import_dialect2.splitRef)(ref, isScopeToken);
+      if (external.has(scope)) return (merged ? (0, import_scopes2.referenceNote)(merged, scope, name) : void 0) ?? true;
       if (opaqueForeign.has(scope)) return true;
       return schema.properties.get(scope)?.has(name) ?? false;
     };
@@ -146,7 +253,7 @@ function validateInterpolation(input, options = {}) {
         const text = t.strings[id];
         if (text === void 0) continue;
         const field = `text[${t.locale}]`;
-        for (const slot of (0, import_dialect.extractSlots)(text)) {
+        for (const slot of (0, import_dialect2.extractSlots)(text)) {
           if (voicedLine) {
             issues.push({
               nodeId,
@@ -167,7 +274,10 @@ function validateInterpolation(input, options = {}) {
             });
             continue;
           }
-          if (!known(slot.ref)) {
+          const ok = known(slot.ref);
+          if (typeof ok === "string") {
+            issues.push({ nodeId, field, src: slot.raw, severity: "warning", message: ok });
+          } else if (!ok) {
             issues.push({
               nodeId,
               field,
@@ -231,11 +341,11 @@ function readOnlyForeignTargets(spec) {
 }
 
 // src/index.ts
-var import_dialect3 = require("@patterkit/dialect");
+var import_dialect4 = require("@patterkit/dialect");
 
 // src/export.ts
 var import_core = require("@patterkit/core");
-var import_dialect2 = require("@patterkit/dialect");
+var import_dialect3 = require("@patterkit/dialect");
 function compileEffect(e, foreign) {
   return { kind: "set", target: e.target, value: compileExpression(e.value, foreign) };
 }
@@ -303,11 +413,37 @@ function compileScene(scene, foreign) {
     blocks: scene.blocks.map((b) => compileBlock(b, foreign))
   };
 }
+function externalScopesIn(scenes, external) {
+  const found = /* @__PURE__ */ new Set();
+  const walk = (node) => {
+    if (!Array.isArray(node) && (node === null || typeof node !== "object")) return;
+    if (Array.isArray(node)) {
+      if (node[0] === "sv" && typeof node[1] === "string" && external.has(node[1])) found.add(node[1]);
+      for (const n of node) walk(n);
+      return;
+    }
+    const o = node;
+    if (o["kind"] === "set" && typeof o["target"] === "string") {
+      const head = o["target"].replace(/^@/, "").split(".")[0];
+      if (o["target"].includes(".") && external.has(head)) found.add(head);
+    }
+    for (const v of Object.values(o)) walk(v);
+  };
+  walk(scenes);
+  return [...found].sort();
+}
 function exportBundle(input) {
   const { project, scenes, locales = [], includeLocales } = input;
-  const foreignScopes = input.foreignScopes ?? (0, import_dialect2.hostScopesToSpec)(project.scopeRegistry);
+  const hostScopes = projectScopes(project, input.gameScopes).host;
+  const foreignScopes = input.foreignScopes ?? (0, import_dialect3.hostScopesToSpec)(hostScopes);
+  const gameExternal = externalGameScopes(foreignScopes, input.gameScopes);
+  const compileScopes = (0, import_dialect3.withEngineScopes)({
+    version: foreignScopes?.version ?? 1,
+    scopes: [...foreignScopes?.scopes ?? [], ...gameExternal.map((s) => ({ token: s.token }))]
+  });
   const scenesOut = {};
-  for (const scene of scenes) scenesOut[scene.id] = compileScene(scene, foreignScopes);
+  for (const scene of scenes) scenesOut[scene.id] = compileScene(scene, compileScopes);
+  const externalScopes = externalScopesIn(scenesOut, /* @__PURE__ */ new Set([...import_dialect3.EXTERNAL_SCOPES, ...gameExternal.map((s) => s.token)]));
   const strings = {};
   for (const loc of locales) {
     if (includeLocales && !includeLocales.includes(loc.locale)) continue;
@@ -357,20 +493,26 @@ function exportBundle(input) {
       return m;
     }),
     properties: project.properties,
-    scopeRegistry: project.scopeRegistry,
+    scopeRegistry: hostScopes,
     gameDataFields: project.gameDataFields,
     // Closed-caption delimiters ride along only when the project pins a non-default pair (#214); the
     // runtime falls back to `[` / `]` when absent, so default projects keep their exact prior bundle.
     ...project.closedCaptions ? { closedCaptions: project.closedCaptions } : {},
     scenes: scenesOut,
-    strings
+    strings,
+    // Other engines' scopes the content names, so the engine can say when the game has not registered one.
+    ...externalScopes.length > 0 ? { externalScopes } : {}
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  EXTERNAL_SCOPES,
+  PATTER_SCOPE,
   compileExpression,
   exportBundle,
+  externalGameScopes,
   hostScopesToSpec,
+  projectScopes,
   validateConditions,
   validateInterpolation
 });

package/dist/index.d.cts

@@ -1,6 +1,7 @@
-import { ScopeRegistrySpec } from '@wildwinter/scoperegistry';
-import { Expression, ProjectFile, Scene, LocaleFile, Bundle } from '@patterkit/model';
-export { hostScopesToSpec } from '@patterkit/dialect';
+import { ScopeRegistrySpec, ScopeSpec } from '@wildwinter/scoperegistry';
+import { MergedScopes } from '@wildwinter/scoperegistry/scopes';
+import { Expression, ProjectFile, Scene, LocaleFile, Bundle, HostScopeRegistry } from '@patterkit/model';
+export { EXTERNAL_SCOPES, hostScopesToSpec } from '@patterkit/dialect';
 
 /**
  * Compile a condition/effect `src` string to the bundle `{ src, ast }` envelope.
@@ -8,6 +9,17 @@ export { hostScopesToSpec } from '@patterkit/dialect';
  * a storylet's `@world`); the parser needs every referenced scope registered.
  */
 declare function compileExpression(src: string, foreign?: ScopeRegistrySpec): Expression;
+/**
+ * What the validators take besides the project. `foreignScopes` is the host spec, checked strictly (a
+ * project's own `@world`, or another owner's spec). `gameScopes` is the game's merged `game-scopes/`
+ * folder: every scope in it the host spec doesn't hold is checked too, but only ever with WARNINGS
+ * (patterkit/design/shared-scopes.md decision 3). Given `gameScopes` and no `foreignScopes`, the host
+ * spec is the project's host scopes as the folder leaves them (`projectScopes`).
+ */
+interface ValidateOptions {
+    foreignScopes?: ScopeRegistrySpec;
+    gameScopes?: MergedScopes;
+}
 interface ConditionIssue {
     /** Id of the node whose expression has the issue. */
     nodeId: string;
@@ -31,9 +43,7 @@ interface ConditionIssue {
 declare function validateConditions(input: {
     project: ProjectFile;
     scenes: Scene[];
-}, options?: {
-    foreignScopes?: ScopeRegistrySpec;
-}): ConditionIssue[];
+}, options?: ValidateOptions): ConditionIssue[];
 /**
  * Validate inline `{@ref}` interpolation slots in a project's localised strings
  * (spec §16). Enforces the VO-safety guarantee - **a voiced project rejects any
@@ -50,9 +60,7 @@ declare function validateInterpolation(input: {
     project: ProjectFile;
     scenes: Scene[];
     locales?: LocaleFile[];
-}, options?: {
-    foreignScopes?: ScopeRegistrySpec;
-}): ConditionIssue[];
+}, options?: ValidateOptions): ConditionIssue[];
 
 interface ExportInput {
     project: ProjectFile;
@@ -67,8 +75,45 @@ interface ExportInput {
      * unregistered scope token, so cross-engine refs need this.
      */
     foreignScopes?: ScopeRegistrySpec;
+    /**
+     * The game's merged `game-scopes/` folder, when the project has one (patterkit/design/shared-scopes.md).
+     * Its `game.scopes.json` wins over the project's copy of a host scope, and its `@world` is baked in
+     * even when the project doesn't declare it; every other scope in it compiles as another engine's
+     * does: named in `externalScopes`, never baked in.
+     */
+    gameScopes?: MergedScopes;
 }
 /** Compile a project's source into the runtime bundle. */
 declare function exportBundle(input: ExportInput): Bundle;
 
-export { type ConditionIssue, type ExportInput, compileExpression, exportBundle, validateConditions, validateInterpolation };
+/** Patter's own game-wide token: the one scope Patter writes to the folder and never reads back. */
+declare const PATTER_SCOPE = "patter";
+/** Something the folder says about the project's host scopes: a warning, anchored to a scopes file. */
+interface HostScopeNote {
+    token: string;
+    /** The scopes file it concerns, by name (`game.scopes.json`). */
+    file: string;
+    message: string;
+}
+/** A project's scopes once its game's folder is taken into account. */
+interface ProjectScopes {
+    /** The host scopes the compile treats as the project's: validated strictly, baked into the bundle. */
+    host?: HostScopeRegistry;
+    /** Every other scope the folder declares, checked with warnings and never bundled. */
+    external: ScopeSpec[];
+    /** Where the project's host scopes and the folder disagree. */
+    notes: HostScopeNote[];
+}
+/**
+ * The project's host scopes and the folder's other scopes, from a project and its game's merged
+ * scopes. With no folder the host scopes are the project's own, untouched (the same object, so a
+ * bundle's hash doesn't move), and there is nothing external.
+ */
+declare function projectScopes(project: ProjectFile, merged?: MergedScopes): ProjectScopes;
+/**
+ * The folder's scopes that a compile treats as external, given the host spec it is using: every merged
+ * scope except Patter's own and the host spec's tokens. Empty with no folder.
+ */
+declare function externalGameScopes(strict: ScopeRegistrySpec | undefined, merged?: MergedScopes): ScopeSpec[];
+
+export { type ConditionIssue, type ExportInput, type HostScopeNote, PATTER_SCOPE, type ProjectScopes, type ValidateOptions, compileExpression, exportBundle, externalGameScopes, projectScopes, validateConditions, validateInterpolation };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { ScopeRegistrySpec } from '@wildwinter/scoperegistry';
-import { Expression, ProjectFile, Scene, LocaleFile, Bundle } from '@patterkit/model';
-export { hostScopesToSpec } from '@patterkit/dialect';
+import { ScopeRegistrySpec, ScopeSpec } from '@wildwinter/scoperegistry';
+import { MergedScopes } from '@wildwinter/scoperegistry/scopes';
+import { Expression, ProjectFile, Scene, LocaleFile, Bundle, HostScopeRegistry } from '@patterkit/model';
+export { EXTERNAL_SCOPES, hostScopesToSpec } from '@patterkit/dialect';
 
 /**
  * Compile a condition/effect `src` string to the bundle `{ src, ast }` envelope.
@@ -8,6 +9,17 @@ export { hostScopesToSpec } from '@patterkit/dialect';
  * a storylet's `@world`); the parser needs every referenced scope registered.
  */
 declare function compileExpression(src: string, foreign?: ScopeRegistrySpec): Expression;
+/**
+ * What the validators take besides the project. `foreignScopes` is the host spec, checked strictly (a
+ * project's own `@world`, or another owner's spec). `gameScopes` is the game's merged `game-scopes/`
+ * folder: every scope in it the host spec doesn't hold is checked too, but only ever with WARNINGS
+ * (patterkit/design/shared-scopes.md decision 3). Given `gameScopes` and no `foreignScopes`, the host
+ * spec is the project's host scopes as the folder leaves them (`projectScopes`).
+ */
+interface ValidateOptions {
+    foreignScopes?: ScopeRegistrySpec;
+    gameScopes?: MergedScopes;
+}
 interface ConditionIssue {
     /** Id of the node whose expression has the issue. */
     nodeId: string;
@@ -31,9 +43,7 @@ interface ConditionIssue {
 declare function validateConditions(input: {
     project: ProjectFile;
     scenes: Scene[];
-}, options?: {
-    foreignScopes?: ScopeRegistrySpec;
-}): ConditionIssue[];
+}, options?: ValidateOptions): ConditionIssue[];
 /**
  * Validate inline `{@ref}` interpolation slots in a project's localised strings
  * (spec §16). Enforces the VO-safety guarantee - **a voiced project rejects any
@@ -50,9 +60,7 @@ declare function validateInterpolation(input: {
     project: ProjectFile;
     scenes: Scene[];
     locales?: LocaleFile[];
-}, options?: {
-    foreignScopes?: ScopeRegistrySpec;
-}): ConditionIssue[];
+}, options?: ValidateOptions): ConditionIssue[];
 
 interface ExportInput {
     project: ProjectFile;
@@ -67,8 +75,45 @@ interface ExportInput {
      * unregistered scope token, so cross-engine refs need this.
      */
     foreignScopes?: ScopeRegistrySpec;
+    /**
+     * The game's merged `game-scopes/` folder, when the project has one (patterkit/design/shared-scopes.md).
+     * Its `game.scopes.json` wins over the project's copy of a host scope, and its `@world` is baked in
+     * even when the project doesn't declare it; every other scope in it compiles as another engine's
+     * does: named in `externalScopes`, never baked in.
+     */
+    gameScopes?: MergedScopes;
 }
 /** Compile a project's source into the runtime bundle. */
 declare function exportBundle(input: ExportInput): Bundle;
 
-export { type ConditionIssue, type ExportInput, compileExpression, exportBundle, validateConditions, validateInterpolation };
+/** Patter's own game-wide token: the one scope Patter writes to the folder and never reads back. */
+declare const PATTER_SCOPE = "patter";
+/** Something the folder says about the project's host scopes: a warning, anchored to a scopes file. */
+interface HostScopeNote {
+    token: string;
+    /** The scopes file it concerns, by name (`game.scopes.json`). */
+    file: string;
+    message: string;
+}
+/** A project's scopes once its game's folder is taken into account. */
+interface ProjectScopes {
+    /** The host scopes the compile treats as the project's: validated strictly, baked into the bundle. */
+    host?: HostScopeRegistry;
+    /** Every other scope the folder declares, checked with warnings and never bundled. */
+    external: ScopeSpec[];
+    /** Where the project's host scopes and the folder disagree. */
+    notes: HostScopeNote[];
+}
+/**
+ * The project's host scopes and the folder's other scopes, from a project and its game's merged
+ * scopes. With no folder the host scopes are the project's own, untouched (the same object, so a
+ * bundle's hash doesn't move), and there is nothing external.
+ */
+declare function projectScopes(project: ProjectFile, merged?: MergedScopes): ProjectScopes;
+/**
+ * The folder's scopes that a compile treats as external, given the host spec it is using: every merged
+ * scope except Patter's own and the host spec's tokens. Empty with no folder.
+ */
+declare function externalGameScopes(strict: ScopeRegistrySpec | undefined, merged?: MergedScopes): ScopeSpec[];
+
+export { type ConditionIssue, type ExportInput, type HostScopeNote, PATTER_SCOPE, type ProjectScopes, type ValidateOptions, compileExpression, exportBundle, externalGameScopes, projectScopes, validateConditions, validateInterpolation };

package/dist/index.js

@@ -1,13 +1,101 @@
 // src/expressions.ts
 import { compile, parse, validateExpr } from "@wildwinter/expr";
-import { dialectWithForeignScopes, buildSchema, extractSlots, splitRef } from "@patterkit/dialect";
+import { dialectWithForeignScopes, buildSchema, extractSlots, splitRef, withEngineScopes, hostScopesToSpec as hostScopesToSpec2 } from "@patterkit/dialect";
+import { referenceNote } from "@wildwinter/scoperegistry/scopes";
+
+// src/game-scopes.ts
+import { GAME_SCOPES_DIR, GAME_SCOPES_FILE } from "@wildwinter/scoperegistry/scopes";
+import { hostScopesToSpec } from "@patterkit/dialect";
+var PATTER_SCOPE = "patter";
+function asHostScope(s) {
+  return {
+    token: s.token,
+    ...s.writable !== void 0 ? { writable: s.writable } : {},
+    ...s.declarations ? { declarations: s.declarations.map((d) => ({ ...d })) } : {}
+  };
+}
+function sameScope(a, b) {
+  const norm = (s) => JSON.stringify(hostScopesToSpec({ version: 1, scopes: [s] }));
+  return norm(a) === norm(b);
+}
+function projectScopes(project, merged) {
+  const own = project.scopeRegistry;
+  if (!merged) return { host: own, external: [], notes: [] };
+  const notes = [];
+  const hosted = [];
+  const bundled = /* @__PURE__ */ new Set();
+  let changed = false;
+  const shared = (token) => token === PATTER_SCOPE ? void 0 : merged.spec.scopes.find((s) => s.token === token);
+  for (const h of own?.scopes ?? []) {
+    const s = shared(h.token);
+    const who = merged.owners.get(h.token);
+    if (!s || !who) {
+      hosted.push(h);
+      bundled.add(h.token);
+      continue;
+    }
+    if (who.fileName === GAME_SCOPES_FILE) {
+      const fromFile = asHostScope(s);
+      hosted.push(fromFile);
+      bundled.add(h.token);
+      changed = true;
+      if (!sameScope(h, fromFile)) {
+        notes.push({
+          token: h.token,
+          file: who.fileName,
+          message: `@${h.token} in World properties differs from ${GAME_SCOPES_DIR}/${who.fileName}, and the shared file wins: saving Project Settings in Patterpad brings the project's copy up to date`
+        });
+      }
+    } else {
+      changed = true;
+      notes.push({
+        token: h.token,
+        file: who.fileName,
+        message: `@${h.token} is declared in ${GAME_SCOPES_DIR}/${who.fileName}; remove it from World properties`
+      });
+    }
+  }
+  const world = shared("world");
+  if (world && merged.owners.get("world")?.fileName === GAME_SCOPES_FILE && !bundled.has("world")) {
+    hosted.push(asHostScope(world));
+    bundled.add("world");
+    changed = true;
+  }
+  const external = merged.spec.scopes.filter((s) => s.token !== PATTER_SCOPE && !bundled.has(s.token));
+  const host = !changed ? own : hosted.length ? { version: own?.version ?? 1, scopes: hosted } : void 0;
+  return { host, external, notes };
+}
+function externalGameScopes(strict, merged) {
+  if (!merged) return [];
+  const hostTokens = new Set((strict?.scopes ?? []).map((s) => s.token));
+  return merged.spec.scopes.filter((s) => s.token !== PATTER_SCOPE && !hostTokens.has(s.token));
+}
+
+// src/expressions.ts
 import { walkNodes } from "@patterkit/model";
 function compileExpression(src, foreign) {
   return compile(src, dialectWithForeignScopes(foreign));
 }
+function validationScopes(project, options) {
+  const merged = options.gameScopes;
+  const strict = options.foreignScopes ?? (merged ? hostScopesToSpec2(projectScopes(project, merged).host) : void 0);
+  const external = externalGameScopes(strict, merged);
+  const base = strict?.scopes ?? [];
+  const foreign = withEngineScopes({ version: strict?.version ?? 1, scopes: [...base, ...external.map((s) => ({ token: s.token }))] });
+  const checked = external.some((s) => s.declarations?.length) ? withEngineScopes({ version: strict?.version ?? 1, scopes: [...base, ...external] }) : void 0;
+  return { foreign, checked, external: new Set(external.map((s) => s.token)), merged };
+}
+var issueKey = (i) => `${i.kind}|${JSON.stringify(i.path)}|${i.message}`;
+function externalMessage(i, merged) {
+  if (merged && i.kind === "unresolved-scoped-property" && i.reference) {
+    const [token, name] = i.reference.split(".");
+    if (token && name) return referenceNote(merged, token, name) ?? i.message;
+  }
+  return i.message;
+}
 function validateConditions(input, options = {}) {
   const issues = [];
-  const foreign = options.foreignScopes;
+  const { foreign, checked, external, merged } = validationScopes(input.project, options);
   const dialect = dialectWithForeignScopes(foreign);
   const readOnly = readOnlyForeignTargets(foreign);
   const opaqueForeign = opaqueForeignTokens(foreign);
@@ -31,6 +119,7 @@ function validateConditions(input, options = {}) {
   };
   const validateElement = (blocks, sceneProps, onEntry, elementId) => {
     const schema = buildSchema(input.project, sceneProps, foreign);
+    const checkedSchema = checked ? buildSchema(input.project, sceneProps, checked) : void 0;
     const check = (nodeId, field, src) => {
       let ast;
       try {
@@ -39,9 +128,16 @@ function validateConditions(input, options = {}) {
         issues.push({ nodeId, field, src, severity: "error", message: e instanceof Error ? e.message : String(e) });
         return;
       }
-      for (const iss of validateExpr(ast, schema, dialect)) {
+      const strict = validateExpr(ast, schema, dialect);
+      for (const iss of strict) {
         issues.push({ nodeId, field, src, severity: iss.severity, message: iss.message });
       }
+      if (checkedSchema) {
+        const seen = new Set(strict.map(issueKey));
+        for (const iss of validateExpr(ast, checkedSchema, dialect)) {
+          if (!seen.has(issueKey(iss))) issues.push({ nodeId, field, src, severity: "warning", message: externalMessage(iss, merged) });
+        }
+      }
       checkVisitIds(ast, nodeId, field, src);
     };
     const checkTarget = (nodeId, field, target) => {
@@ -66,6 +162,11 @@ function validateConditions(input, options = {}) {
         return;
       }
       const { scope, name } = splitRef(target, isScopeToken);
+      if (external.has(scope)) {
+        const note = merged ? referenceNote(merged, scope, name, { write: true }) : void 0;
+        if (note) issues.push({ nodeId, field, src: target, severity: "warning", message: note });
+        return;
+      }
       if (opaqueForeign.has(scope)) return;
       if (!schema.properties.get(scope)?.has(name)) {
         issues.push({
@@ -102,12 +203,14 @@ function validateInterpolation(input, options = {}) {
   const voiced = input.project.voiced ?? false;
   const tables = (input.locales ?? []).map((l) => ({ locale: l.locale, strings: l.strings }));
   const defaultLocale = input.project.locales.default;
-  const opaqueForeign = opaqueForeignTokens(options.foreignScopes);
-  const isScopeToken = scopeTokenTest(options.foreignScopes);
+  const { foreign, external, merged } = validationScopes(input.project, options);
+  const opaqueForeign = opaqueForeignTokens(foreign);
+  const isScopeToken = scopeTokenTest(foreign);
   for (const scene of input.scenes) {
-    const schema = buildSchema(input.project, scene.sceneProps, options.foreignScopes);
+    const schema = buildSchema(input.project, scene.sceneProps, foreign);
     const known = (ref) => {
       const { scope, name } = splitRef(ref, isScopeToken);
+      if (external.has(scope)) return (merged ? referenceNote(merged, scope, name) : void 0) ?? true;
       if (opaqueForeign.has(scope)) return true;
       return schema.properties.get(scope)?.has(name) ?? false;
     };
@@ -137,7 +240,10 @@ function validateInterpolation(input, options = {}) {
             });
             continue;
           }
-          if (!known(slot.ref)) {
+          const ok = known(slot.ref);
+          if (typeof ok === "string") {
+            issues.push({ nodeId, field, src: slot.raw, severity: "warning", message: ok });
+          } else if (!ok) {
             issues.push({
               nodeId,
               field,
@@ -201,11 +307,11 @@ function readOnlyForeignTargets(spec) {
 }
 
 // src/index.ts
-import { hostScopesToSpec as hostScopesToSpec2 } from "@patterkit/dialect";
+import { hostScopesToSpec as hostScopesToSpec4, EXTERNAL_SCOPES as EXTERNAL_SCOPES2 } from "@patterkit/dialect";
 
 // src/export.ts
 import { canonicalStringify, hash32 } from "@patterkit/core";
-import { hostScopesToSpec } from "@patterkit/dialect";
+import { hostScopesToSpec as hostScopesToSpec3, withEngineScopes as withEngineScopes2, EXTERNAL_SCOPES } from "@patterkit/dialect";
 function compileEffect(e, foreign) {
   return { kind: "set", target: e.target, value: compileExpression(e.value, foreign) };
 }
@@ -273,11 +379,37 @@ function compileScene(scene, foreign) {
     blocks: scene.blocks.map((b) => compileBlock(b, foreign))
   };
 }
+function externalScopesIn(scenes, external) {
+  const found = /* @__PURE__ */ new Set();
+  const walk = (node) => {
+    if (!Array.isArray(node) && (node === null || typeof node !== "object")) return;
+    if (Array.isArray(node)) {
+      if (node[0] === "sv" && typeof node[1] === "string" && external.has(node[1])) found.add(node[1]);
+      for (const n of node) walk(n);
+      return;
+    }
+    const o = node;
+    if (o["kind"] === "set" && typeof o["target"] === "string") {
+      const head = o["target"].replace(/^@/, "").split(".")[0];
+      if (o["target"].includes(".") && external.has(head)) found.add(head);
+    }
+    for (const v of Object.values(o)) walk(v);
+  };
+  walk(scenes);
+  return [...found].sort();
+}
 function exportBundle(input) {
   const { project, scenes, locales = [], includeLocales } = input;
-  const foreignScopes = input.foreignScopes ?? hostScopesToSpec(project.scopeRegistry);
+  const hostScopes = projectScopes(project, input.gameScopes).host;
+  const foreignScopes = input.foreignScopes ?? hostScopesToSpec3(hostScopes);
+  const gameExternal = externalGameScopes(foreignScopes, input.gameScopes);
+  const compileScopes = withEngineScopes2({
+    version: foreignScopes?.version ?? 1,
+    scopes: [...foreignScopes?.scopes ?? [], ...gameExternal.map((s) => ({ token: s.token }))]
+  });
   const scenesOut = {};
-  for (const scene of scenes) scenesOut[scene.id] = compileScene(scene, foreignScopes);
+  for (const scene of scenes) scenesOut[scene.id] = compileScene(scene, compileScopes);
+  const externalScopes = externalScopesIn(scenesOut, /* @__PURE__ */ new Set([...EXTERNAL_SCOPES, ...gameExternal.map((s) => s.token)]));
   const strings = {};
   for (const loc of locales) {
     if (includeLocales && !includeLocales.includes(loc.locale)) continue;
@@ -327,19 +459,25 @@ function exportBundle(input) {
       return m;
     }),
     properties: project.properties,
-    scopeRegistry: project.scopeRegistry,
+    scopeRegistry: hostScopes,
     gameDataFields: project.gameDataFields,
     // Closed-caption delimiters ride along only when the project pins a non-default pair (#214); the
     // runtime falls back to `[` / `]` when absent, so default projects keep their exact prior bundle.
     ...project.closedCaptions ? { closedCaptions: project.closedCaptions } : {},
     scenes: scenesOut,
-    strings
+    strings,
+    // Other engines' scopes the content names, so the engine can say when the game has not registered one.
+    ...externalScopes.length > 0 ? { externalScopes } : {}
   };
 }
 export {
+  EXTERNAL_SCOPES2 as EXTERNAL_SCOPES,
+  PATTER_SCOPE,
   compileExpression,
   exportBundle,
-  hostScopesToSpec2 as hostScopesToSpec,
+  externalGameScopes,
+  hostScopesToSpec4 as hostScopesToSpec,
+  projectScopes,
   validateConditions,
   validateInterpolation
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/compiler",
-  "version": "0.2.8",
+  "version": "0.4.0",
   "description": "Patter compiler: compile condition/effect expressions, validate them, and export source to the runtime bundle.",
   "type": "module",
   "license": "MIT",
@@ -34,10 +34,10 @@
     "build": "tsup src/index.ts --format esm,cjs --dts --clean"
   },
   "dependencies": {
-    "@patterkit/model": "0.5.0",
-    "@patterkit/core": "0.2.4",
-    "@patterkit/dialect": "0.1.9",
+    "@patterkit/model": "0.7.0",
+    "@patterkit/core": "0.2.6",
+    "@patterkit/dialect": "0.2.1",
     "@wildwinter/expr": "^0.5.0",
-    "@wildwinter/scoperegistry": "^0.6.0"
+    "@wildwinter/scoperegistry": "^0.8.0"
   }
 }