@neocompose/cli 0.65.1 → 0.66.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.66.0] - 2026-10-03
+
+- Add the 18 script runtime lifecycle interfaces from P98, such as `INeoOnLoad`, `INeoUnityUpdate`, and `INeoUnityOnTriggerEnter2D`. Every project gets them as protected system records, and pull writes them under `Interfaces/System/` with `@system(kind: .ScriptRuntime)`.
+- Reserve the lifecycle member names, such as `OnLoad` and `Update`. A member with one must be the public, immediate instance method implementing its interface, or it reports `reserved-lifecycle-member`. This tightens valid source: a project with an unrelated member by one of these names must rename it. Push enforces the same rule on records authored in the web editor.
+- Report `lifecycle-hook-without-object` as a warning when a class reaches an `INeoUnity*` interface without extending `NeoObjectBase`. Push still succeeds.
+- A lifecycle hook cannot be `@effect`. It reports `invalid-effect`.
+
 ## [0.65.1] - 2026-10-03
 
 - Pull and push reconciliation emit a stored `new NeoAnimationSegmentFrame<NeoCollider?>(value: null)`. A null constructor argument typed by a class's generic parameter now checks nullability against the row's type argument. Previously, a pushed segment holding a null frame committed, but source reconciliation failed with "Required constructor argument stores null".

package/dist/neo.mjs

@@ -5959,6 +5959,10 @@ var init_neoflow_graph_parser = __esm({
 });
 
 // ../packages/neoscript-language/src/project-source-ast.ts
+function neoSourceTypeText(type) {
+  const args = type.typeArguments.length > 0 ? `<${type.typeArguments.map(neoSourceTypeText).join(", ")}>` : "";
+  return `${type.name}${args}${type.nullable ? "?" : ""}`;
+}
 function isNeoSourceAccessModifier(value) {
   return value === "public" || value === "protected" || value === "private";
 }
@@ -7892,6 +7896,9 @@ function tripleInterpolationEnd(text, start, limit) {
   }
   return null;
 }
+function rangesEqual(left, right) {
+  return positionCompare(left.start, right.start) === 0 && positionCompare(left.end, right.end) === 0;
+}
 function positionCompare(left, right) {
   return left.line === right.line ? left.character - right.character : left.line - right.line;
 }
@@ -8367,7 +8374,8 @@ var init_project_schema_contract_generated = __esm({
           "DialogueMemoryContainer",
           "DialoguePriorityDefault",
           "PolicyImmutable",
-          "PolicyDeleteBlocked"
+          "PolicyDeleteBlocked",
+          "ScriptRuntime"
         ],
         "NeoMemberRequirement": [
           "Optional",
@@ -26424,6 +26432,40 @@ var init_project_source_script_compiler = __esm({
   }
 });
 
+// ../packages/neoscript-language/src/project-source-lifecycle-hooks.ts
+function isScriptRuntimeInterface(declaration) {
+  const kind = declaration.annotations.find((annotation2) => annotation2.name === "system")?.arguments.find((argument2) => argument2.name === "kind")?.text.trim();
+  return kind === ".ScriptRuntime";
+}
+function lifecycleHooksByMemberName(interfaces) {
+  const hooks = /* @__PURE__ */ new Map();
+  for (const declaration of interfaces) {
+    if (!isScriptRuntimeInterface(declaration)) continue;
+    for (const member of declaration.members) {
+      if (member.kind !== "function") continue;
+      hooks.set(member.name.toLowerCase(), {
+        interfaceName: declaration.name,
+        member,
+        ...declaration.docsText === void 0 ? {} : { docsText: declaration.docsText },
+        unity: declaration.name.startsWith(UNITY_LIFECYCLE_INTERFACE_PREFIX)
+      });
+    }
+  }
+  return hooks;
+}
+function reservedLifecycleMemberMessage(memberName, interfaceName, owner) {
+  const fix = owner === "class" ? "Implement the interface with a public method" : "Extend the interface";
+  return `'${memberName}' is reserved for '${interfaceName}'. ${fix}, or rename the member.`;
+}
+var NEO_LIFECYCLE_OBJECT_CLASS_NAME, UNITY_LIFECYCLE_INTERFACE_PREFIX;
+var init_project_source_lifecycle_hooks = __esm({
+  "../packages/neoscript-language/src/project-source-lifecycle-hooks.ts"() {
+    "use strict";
+    NEO_LIFECYCLE_OBJECT_CLASS_NAME = "NeoObjectBase";
+    UNITY_LIFECYCLE_INTERFACE_PREFIX = "INeoUnity";
+  }
+});
+
 // ../packages/neoscript-language/src/project-source-type-checker.ts
 function validateProjectSourceTypes(documents) {
   const diagnostics = [];
@@ -26433,6 +26475,7 @@ function validateProjectSourceTypes(documents) {
   validateInheritanceCycles(environment, diagnostics);
   validateAllTypeApplications(documents, environment, diagnostics);
   validateMembers(environment, diagnostics);
+  validateLifecycleHooks(environment, diagnostics);
   return diagnostics;
 }
 function createEnvironment2(documents) {
@@ -26489,7 +26532,16 @@ function createEnvironment2(documents) {
       }
     }
   }
-  return { declarations, classes, interfaces, memberOwners, typeKinds };
+  return {
+    declarations,
+    classes,
+    interfaces,
+    memberOwners,
+    typeKinds,
+    lifecycleHooks: lifecycleHooksByMemberName(
+      [...interfaces.values()].map((ref) => ref.declaration)
+    )
+  };
 }
 function validatePersistedNames(documents, diagnostics) {
   for (const [uri, document] of documents) {
@@ -27500,7 +27552,7 @@ function validateEffects(ref, environment, diagnostics) {
       kind = inheritedEffectKind(inherited, member.name);
     }
     if (kind !== "Auto") continue;
-    const problem = effectIneligibility(member);
+    const problem = effectIneligibility(member) ?? (environment.lifecycleHooks.has(member.name.toLowerCase()) ? "the runtime already calls a lifecycle hook, so its first run would happen twice" : null);
     if (problem === null) continue;
     diagnose(
       diagnostics,
@@ -27550,6 +27602,110 @@ function effectIneligibility(member) {
   if (member.parameters.length > 0) return "an effect takes no parameters";
   return null;
 }
+function validateLifecycleHooks(environment, diagnostics) {
+  const hooks = environment.lifecycleHooks;
+  if (hooks.size === 0) return;
+  for (const ref of environment.interfaces.values()) {
+    if (isScriptRuntimeInterface(ref.declaration)) continue;
+    for (const member of ref.declaration.members) {
+      const hook = hooks.get(member.name.toLowerCase());
+      if (hook === void 0) continue;
+      diagnose(
+        diagnostics,
+        ref.uri,
+        member.nameRange,
+        "reserved-lifecycle-member",
+        reservedLifecycleMemberMessage(
+          member.name,
+          hook.interfaceName,
+          "interface"
+        )
+      );
+    }
+  }
+  const unityHookByInterface = /* @__PURE__ */ new Map();
+  for (const ref of environment.classes.values()) {
+    if (ref.sourceKind === "flow") continue;
+    let implemented;
+    for (const member of ref.declaration.members) {
+      const hook = hooks.get(member.name.toLowerCase());
+      if (hook === void 0) continue;
+      implemented ??= new Set(
+        implementedInterfaces(ref, environment).map(
+          (view) => view.owner.declaration.name
+        )
+      );
+      if (member.kind === "function" && effectiveSourceAccessModifier(member.modifiers, "class") === "public" && !member.modifiers.includes("static") && !member.modifiers.includes("async") && implemented.has(hook.interfaceName)) {
+        continue;
+      }
+      diagnose(
+        diagnostics,
+        ref.uri,
+        member.nameRange,
+        "reserved-lifecycle-member",
+        reservedLifecycleMemberMessage(
+          member.name,
+          hook.interfaceName,
+          "class"
+        )
+      );
+    }
+    let rendersObjects;
+    for (const base of ref.declaration.baseTypes) {
+      const target = environment.interfaces.get(base.name);
+      if (target === void 0) continue;
+      const unityHook = unityHookReachedBy(
+        target,
+        environment,
+        unityHookByInterface
+      );
+      if (unityHook === null) continue;
+      rendersObjects ??= extendsLifecycleObjectClass(ref, environment);
+      if (rendersObjects) break;
+      diagnostics.push({
+        uri: ref.uri,
+        range: base.range,
+        severity: "warning",
+        source: "neo-project",
+        code: "lifecycle-hook-without-object",
+        message: `'${unityHook}' does nothing on '${ref.declaration.name}'. Only classes that extend ${NEO_LIFECYCLE_OBJECT_CLASS_NAME} get Unity lifecycle calls.`
+      });
+    }
+  }
+}
+function unityHookReachedBy(ref, environment, memo) {
+  const name = ref.declaration.name;
+  const known = memo.get(name);
+  if (known !== void 0) return known;
+  memo.set(name, null);
+  let reached = null;
+  if (isScriptRuntimeInterface(ref.declaration) && ref.declaration.members.some(
+    (member) => environment.lifecycleHooks.get(member.name.toLowerCase())?.unity === true
+  )) {
+    reached = name;
+  }
+  for (const base of ref.declaration.baseTypes) {
+    if (reached !== null) break;
+    const target = environment.interfaces.get(base.name);
+    if (target !== void 0) {
+      reached = unityHookReachedBy(target, environment, memo);
+    }
+  }
+  memo.set(name, reached);
+  return reached;
+}
+function extendsLifecycleObjectClass(ref, environment) {
+  const visited = /* @__PURE__ */ new Set();
+  let current = ref;
+  while (current !== null && !visited.has(current.declaration.name)) {
+    if (current.declaration.name === NEO_LIFECYCLE_OBJECT_CLASS_NAME) {
+      return true;
+    }
+    visited.add(current.declaration.name);
+    current = classBase(current, identitySubstitution(current), environment)?.owner ?? null;
+  }
+  return false;
+}
 function isPlatformImplementedSystemMember(member) {
   if (!member.modifiers.includes("protected")) return false;
   return member.annotations.some((entry) => entry.name === "system");
@@ -28019,6 +28175,7 @@ var init_project_source_type_checker = __esm({
     init_strict_compile_error();
     init_project_source_accessors();
     init_project_source_identifiers();
+    init_project_source_lifecycle_hooks();
     BUILTIN_ARITY = /* @__PURE__ */ new Map([
       ["List", 1],
       ["Set", 1],
@@ -28208,12 +28365,12 @@ function classifyConstantExpression(expression) {
 function defaultTypeMismatch(type, constant, enumOptions, parameterName) {
   if (constant.kind === "null") {
     if (type.nullable) return null;
-    return `Parameter '${parameterName}' defaults to null, but its type '${formatSourceType(type)}' is not nullable.`;
+    return `Parameter '${parameterName}' defaults to null, but its type '${neoSourceTypeText(type)}' is not nullable.`;
   }
   const declaredEnumOptions = enumOptions.get(type.name);
   if (constant.kind === "enumOption") {
     if (declaredEnumOptions === void 0) {
-      return `Parameter '${parameterName}' defaults to enum option '.${constant.optionName}', but its type '${formatSourceType(type)}' is not an enum.`;
+      return `Parameter '${parameterName}' defaults to enum option '.${constant.optionName}', but its type '${neoSourceTypeText(type)}' is not an enum.`;
     }
     if (!declaredEnumOptions.has(constant.optionName)) {
       return `Parameter '${parameterName}' defaults to '.${constant.optionName}', which enum '${type.name}' does not declare.`;
@@ -28222,9 +28379,9 @@ function defaultTypeMismatch(type, constant, enumOptions, parameterName) {
   }
   if (constantKindMatchesPrimitive(type.name, constant.kind)) return null;
   if (PRIMITIVE_PARAMETER_TYPES.has(type.name) || declaredEnumOptions !== void 0) {
-    return `Parameter '${parameterName}' default is a ${describeConstant(constant)}, which does not match its declared type '${formatSourceType(type)}'.`;
+    return `Parameter '${parameterName}' default is a ${describeConstant(constant)}, which does not match its declared type '${neoSourceTypeText(type)}'.`;
   }
-  return `Parameter '${parameterName}' of type '${formatSourceType(type)}' can only default to null${type.nullable ? "" : ", and only when the type is nullable"}.`;
+  return `Parameter '${parameterName}' of type '${neoSourceTypeText(type)}' can only default to null${type.nullable ? "" : ", and only when the type is nullable"}.`;
 }
 function constantKindMatchesPrimitive(typeName, kind) {
   if (typeName === "bool") return kind === "bool";
@@ -28240,15 +28397,12 @@ function describeConstant(constant) {
   if (constant.kind === "int") return "whole-number literal";
   return "fractional number literal";
 }
-function formatSourceType(type) {
-  const argumentsText = type.typeArguments.length === 0 ? "" : `<${type.typeArguments.map(formatSourceType).join(", ")}>`;
-  return `${type.name}${argumentsText}${type.nullable ? "?" : ""}`;
-}
 var PARAMETER_DEFAULT_DIAGNOSTIC_CODES, DEFAULT_BEFORE_REQUIRED_PARAMETER, PARAMETER_DEFAULT_TYPE_MISMATCH, NON_CONSTANT_PARAMETER_DEFAULT, PARAMETER_DEFAULT_ON_DEFERRED_FUNCTION, PRIMITIVE_PARAMETER_TYPES;
 var init_project_source_parameter_defaults = __esm({
   "../packages/neoscript-language/src/project-source-parameter-defaults.ts"() {
     "use strict";
     init_language_spec();
+    init_project_source_ast();
     init_executable_parser();
     PARAMETER_DEFAULT_DIAGNOSTIC_CODES = {
       defaultBeforeRequiredParameter: "default-before-required-parameter",
@@ -29955,7 +30109,7 @@ var init_registry = __esm({
   "../packages/manifest/schema-contract/registry.mjs"() {
     "use strict";
     PROJECT_SCHEMA_CONTRACT = Object.freeze({
-      cliVersion: "0.65.1",
+      cliVersion: "0.66.0",
       projectFileUploadBatchSize: 32,
       documentRecords: {
         member: {
@@ -30660,7 +30814,8 @@ var init_registry = __esm({
               "DialogueMemoryContainer",
               "DialoguePriorityDefault",
               "PolicyImmutable",
-              "PolicyDeleteBlocked"
+              "PolicyDeleteBlocked",
+              "ScriptRuntime"
             ],
             NeoMemberRequirement: ["Optional", "Required"],
             NeoMemberMutability: ["Mutable", "ReadOnly"],
@@ -34170,7 +34325,8 @@ var init_schema_member = __esm({
       "dialogueMemoryContainer",
       "dialoguePriorityDefault",
       "policyImmutable",
-      "policyDeleteBlocked"
+      "policyDeleteBlocked",
+      "scriptRuntime"
     ]);
     worldSystemClassKindSchema = picklist([
       "cellPattern",
@@ -35728,7 +35884,8 @@ function isSchemaSystemMetadata(value) {
     "dialogueMemoryContainer",
     "dialoguePriorityDefault",
     "policyImmutable",
-    "policyDeleteBlocked"
+    "policyDeleteBlocked",
+    "scriptRuntime"
   ]);
   const worlds = /* @__PURE__ */ new Set([
     "cellPattern",
@@ -40146,7 +40303,7 @@ function isEpochMillis(value) {
   return Number.isFinite(value);
 }
 function isSystemProtectionKind(value) {
-  return value === SystemProtectionKind.WorldAuthoring || value === SystemProtectionKind.DialogueMemorySchema || value === SystemProtectionKind.DialogueMemoryContainer || value === SystemProtectionKind.DialoguePriorityDefault || value === SystemProtectionKind.PolicyImmutable || value === SystemProtectionKind.PolicyDeleteBlocked;
+  return value === SystemProtectionKind.WorldAuthoring || value === SystemProtectionKind.DialogueMemorySchema || value === SystemProtectionKind.DialogueMemoryContainer || value === SystemProtectionKind.DialoguePriorityDefault || value === SystemProtectionKind.PolicyImmutable || value === SystemProtectionKind.PolicyDeleteBlocked || value === SystemProtectionKind.ScriptRuntime;
 }
 function isSystemMetadata(value) {
   const v = value;
@@ -40190,7 +40347,8 @@ var init_core_types = __esm({
       DialogueMemoryContainer: "dialogueMemoryContainer",
       DialoguePriorityDefault: "dialoguePriorityDefault",
       PolicyImmutable: "policyImmutable",
-      PolicyDeleteBlocked: "policyDeleteBlocked"
+      PolicyDeleteBlocked: "policyDeleteBlocked",
+      ScriptRuntime: "scriptRuntime"
     };
   }
 });
@@ -52216,7 +52374,9 @@ function emitInterface(context, value) {
     const deferred = member.deferred ? "async " : "";
     return `${emitDocsText(member.docsText)}${id(member.id)}${access}${deferred}${renderReturnType(context, member.returnType)} ${member.name}(${member.arguments.map((argument2) => renderParameter(context, argument2)).join(", ")});`;
   });
-  return `${emitDocsText(value.docsText)}${id(value.id)}interface ${value.name}${bases.length ? ` : ${bases.join(", ")}` : ""} {
+  const system = value.system ? `${systemAnnotation2(value.system)}
+` : "";
+  return `${emitDocsText(value.docsText)}${id(value.id)}${system}interface ${value.name}${bases.length ? ` : ${bases.join(", ")}` : ""} {
 ${members.map((member) => indentNeoSourceNonEmptyLines(member, 2)).join("\n\n")}
 }
 `;
@@ -109581,6 +109741,14 @@ var init_system_protection = __esm({
         disallow: [SystemDisallowedOperation.DeleteRecord],
         reasonKey: "systemProtection.reasons.policyDeleteBlocked",
         serverReason: "System default policy may be edited but must keep one default row."
+      },
+      [SystemProtectionKind.ScriptRuntime]: {
+        disallow: [
+          SystemDisallowedOperation.EditRecord,
+          SystemDisallowedOperation.DeleteRecord
+        ],
+        reasonKey: "systemProtection.reasons.scriptRuntime",
+        serverReason: "Lifecycle interface the Neo Compose script runtime calls."
       }
     };
   }
@@ -142417,6 +142585,260 @@ var init_analyzer = __esm({
   }
 });
 
+// ../packages/neoscript-language/src/project-source-lifecycle-editor.ts
+function projectLifecycleHooks(analysis) {
+  let hooks = PROJECT_LIFECYCLE_HOOKS.get(analysis);
+  if (!hooks) {
+    const interfaces = [];
+    for (const document of analysis.documents.values()) {
+      for (const declaration of document.declarations) {
+        if (declaration.kind === "interface") interfaces.push(declaration);
+      }
+    }
+    hooks = lifecycleHooksByMemberName(interfaces);
+    PROJECT_LIFECYCLE_HOOKS.set(analysis, hooks);
+  }
+  return hooks;
+}
+function projectLifecycleQuickFixes(analysis, document, diagnostic, findType) {
+  if (diagnostic.code !== "reserved-lifecycle-member") return [];
+  const source = analysis.documents.get(document.uri);
+  if (!source) return [];
+  for (const declaration of source.declarations) {
+    if (declaration.kind !== "class") continue;
+    const member = declaration.members.find(
+      (candidate) => rangesEqual(candidate.nameRange, diagnostic.range)
+    );
+    if (member?.kind !== "function") continue;
+    const hook = projectLifecycleHooks(analysis).get(member.name.toLowerCase());
+    if (hook === void 0) return [];
+    const text = new SourceText(document.text);
+    const tokens = source.syntax.tokens;
+    const edits = [];
+    if (!classLifecycleContext(declaration, findType).implemented.has(
+      hook.interfaceName
+    )) {
+      edits.push(baseListEdit(text, tokens, declaration, hook.interfaceName));
+    }
+    if (effectiveSourceAccessModifier(member.modifiers, "class") !== "public") {
+      edits.push(publicAccessEdit(text, tokens, member));
+    }
+    if (edits.length === 0) return [];
+    return [
+      {
+        title: `Implement '${hook.interfaceName}'`,
+        kind: "quickfix",
+        diagnostics: [diagnostic],
+        edit: { changes: { [document.uri]: edits } },
+        preferred: true
+      }
+    ];
+  }
+  return [];
+}
+function lifecycleMemberCompletions(analysis, document, position, findType) {
+  const hooks = projectLifecycleHooks(analysis);
+  if (hooks.size === 0) return [];
+  const source = analysis.documents.get(document.uri);
+  const declaration = source?.declarations.find(
+    (candidate) => candidate.kind === "class" && positionCompare(candidate.range.start, position) < 0 && positionCompare(position, candidate.range.end) < 0
+  );
+  if (!source || source.kind === "flow" || !declaration) return [];
+  const text = new SourceText(document.text);
+  const offset = text.offsetAt(position);
+  const site = memberDeclarationSite(
+    source.syntax.tokens,
+    declaration,
+    text,
+    offset
+  );
+  if (site === null) return [];
+  const own = new Set(
+    declaration.members.map((member) => member.name.toLowerCase())
+  );
+  const context = classLifecycleContext(declaration, findType);
+  const range2 = text.range(site.start, site.end);
+  const typed = document.text.slice(site.start, site.modifiersEnd).trim();
+  const items = [];
+  for (const [key, hook] of hooks) {
+    if (own.has(key)) continue;
+    if (hook.unity && !context.rendersObjects) continue;
+    const inherited = context.inherited.get(key);
+    if (inherited !== void 0 && !isOverridable(inherited)) continue;
+    const name = hook.member.name;
+    const snippet = `public ${inherited === void 0 ? "" : "override "}${hookSignature(hook.member)} {
+  $0
+}`;
+    items.push({
+      label: name,
+      kind: "method",
+      detail: hook.interfaceName,
+      ...hook.docsText === void 0 ? {} : { documentation: hook.docsText.split("\n")[0] },
+      insertText: snippet,
+      insertTextFormat: "snippet",
+      filterText: typed.length === 0 ? name : `${typed} ${name}`,
+      textEdit: { range: range2, newText: snippet },
+      ...context.implemented.has(hook.interfaceName) ? {} : {
+        additionalTextEdits: [
+          baseListEdit(
+            text,
+            source.syntax.tokens,
+            declaration,
+            hook.interfaceName
+          )
+        ]
+      }
+    });
+  }
+  return items;
+}
+function lifecycleHoverMarkdown(analysis, memberName) {
+  const hook = projectLifecycleHooks(analysis).get(memberName.toLowerCase());
+  if (hook === void 0) return "";
+  const docs = hook.docsText === void 0 ? "" : ` ${hook.docsText}`;
+  return `
+
+Lifecycle hook from \`${hook.interfaceName}\`.${docs}`;
+}
+function classLifecycleContext(declaration, findType) {
+  const implemented = /* @__PURE__ */ new Set();
+  const inherited = /* @__PURE__ */ new Map();
+  const pendingInterfaces = [];
+  const visitedClasses = /* @__PURE__ */ new Set();
+  let rendersObjects = false;
+  let current = declaration;
+  while (current !== void 0 && !visitedClasses.has(current.name)) {
+    visitedClasses.add(current.name);
+    if (current.name === NEO_LIFECYCLE_OBJECT_CLASS_NAME) rendersObjects = true;
+    if (current !== declaration) {
+      for (const member of current.members) {
+        const key = member.name.toLowerCase();
+        if (!inherited.has(key)) inherited.set(key, member);
+      }
+    }
+    let next;
+    for (const base of current.baseTypes) {
+      const target = findType(base.name);
+      if (target?.kind === "class") next ??= target;
+      else if (target?.kind === "interface") pendingInterfaces.push(target);
+    }
+    current = next;
+  }
+  while (pendingInterfaces.length > 0) {
+    const target = pendingInterfaces.pop();
+    if (implemented.has(target.name)) continue;
+    implemented.add(target.name);
+    for (const base of target.baseTypes) {
+      const parent = findType(base.name);
+      if (parent?.kind === "interface") pendingInterfaces.push(parent);
+    }
+  }
+  return { implemented, rendersObjects, inherited };
+}
+function isOverridable(member) {
+  if (member.modifiers.includes("sealed")) return false;
+  return member.modifiers.includes("virtual") || member.modifiers.includes("abstract") || member.modifiers.includes("override");
+}
+function hookSignature(member) {
+  const parameters = member.parameters.map(
+    (parameter4) => `${neoSourceTypeText(parameter4.type)} ${parameter4.name}`
+  ).join(", ");
+  return `${neoSourceTypeText(member.type)} ${member.name}(${parameters})`;
+}
+function baseListEdit(text, tokens, declaration, interfaceName) {
+  const last = declaration.baseTypes[declaration.baseTypes.length - 1];
+  if (last !== void 0) {
+    const end = declaration.baseTypes.length === 1 && declaration.baseClause ? declaration.baseClause.range.end : last.range.end;
+    const at4 = text.offsetAt(end);
+    return { range: text.range(at4, at4), newText: `, ${interfaceName}` };
+  }
+  const at3 = headerEnd(tokens, text.offsetAt(declaration.nameRange.end));
+  return { range: text.range(at3, at3), newText: ` : ${interfaceName}` };
+}
+function headerEnd(tokens, nameEnd) {
+  let end = nameEnd;
+  let depth = 0;
+  for (const token of tokens) {
+    if (token.start < nameEnd || token.kind === "comment") continue;
+    if (token.text === "(") depth += 1;
+    else if (token.text === ")") depth -= 1;
+    else if (depth === 0 && token.text === "{") break;
+    end = token.end;
+  }
+  return end;
+}
+function publicAccessEdit(text, tokens, member) {
+  const start = text.offsetAt(member.range.start);
+  const typeStart = text.offsetAt(member.type.range.start);
+  let firstModifier;
+  let depth = 0;
+  for (const token of tokens) {
+    if (token.start < start || token.kind === "comment") continue;
+    if (token.start >= typeStart) break;
+    if (token.text === "(") depth += 1;
+    else if (token.text === ")") depth -= 1;
+    if (depth !== 0 || token.kind !== "keyword") continue;
+    if (isNeoSourceAccessModifier(token.text)) {
+      return { range: token.range, newText: "public" };
+    }
+    firstModifier ??= token;
+  }
+  const at3 = firstModifier?.start ?? typeStart;
+  return { range: text.range(at3, at3), newText: "public " };
+}
+function memberDeclarationSite(tokens, declaration, text, offset) {
+  const headerEndOffset = text.offsetAt(
+    declaration.baseClause?.range.end ?? declaration.nameRange.end
+  );
+  const classStart = text.offsetAt(declaration.range.start);
+  const before = [];
+  let depth = 0;
+  for (const token of tokens) {
+    if (token.start < classStart || token.kind === "comment") continue;
+    if (token.kind === "eof" || token.start >= offset) break;
+    before.push(token);
+    if (token.start < headerEndOffset || token.interpolationHole) continue;
+    if (token.text === "{") depth += 1;
+    else if (token.text === "}") depth -= 1;
+  }
+  if (depth !== 1) return null;
+  let index = before.length - 1;
+  let end = offset;
+  let word = before[index];
+  if (word !== void 0 && (word.kind === "identifier" || word.kind === "type") && word.end === offset) {
+    index -= 1;
+  } else {
+    word = void 0;
+  }
+  let start = word?.start ?? offset;
+  const modifiersEnd = start;
+  while (MEMBER_SITE_MODIFIERS.has(before[index]?.text ?? "")) {
+    start = before[index].start;
+    index -= 1;
+  }
+  const boundary = before[index]?.text;
+  if (boundary !== "{" && boundary !== "}" && boundary !== ";") return null;
+  if (word !== void 0) end = word.end;
+  return { start, modifiersEnd, end };
+}
+var PROJECT_LIFECYCLE_HOOKS, MEMBER_SITE_MODIFIERS;
+var init_project_source_lifecycle_editor = __esm({
+  "../packages/neoscript-language/src/project-source-lifecycle-editor.ts"() {
+    "use strict";
+    init_project_source_ast();
+    init_project_source_lifecycle_hooks();
+    init_project_source_tokens();
+    init_source_text();
+    PROJECT_LIFECYCLE_HOOKS = /* @__PURE__ */ new WeakMap();
+    MEMBER_SITE_MODIFIERS = /* @__PURE__ */ new Set([
+      "public",
+      "protected",
+      "private",
+      "override"
+    ]);
+  }
+});
+
 // ../packages/neoscript-language/src/quick-fixes.ts
 function quickFixFor(document, diagnostic) {
   if (diagnostic.code === "missing-semicolon") {
@@ -142895,6 +143317,16 @@ function projectFallbackCompletions(analysis, document, position) {
     document,
     position
   );
+  if (!expression && !classBasePosition) {
+    for (const item of lifecycleMemberCompletions(
+      analysis,
+      document,
+      position,
+      (name) => findTypeDeclaration(analysis, name)
+    )) {
+      items.set(`${item.detail}.${item.label}`, item);
+    }
+  }
   const keywords = expression ? afterNew ? [] : ["new"] : typePosition ? [] : [
     "class",
     "interface",
@@ -143338,7 +143770,7 @@ function declaredConstructorNamedArguments(analysis, typeName, used) {
 function parameterArgumentField(parameter4) {
   return {
     name: parameter4.name,
-    type: sourceTypeText(parameter4.type),
+    type: neoSourceTypeText(parameter4.type),
     ...parameter4.defaultValue === void 0 ? {} : { defaultText: parameter4.defaultValue.text }
   };
 }
@@ -143358,7 +143790,7 @@ function projectInitializerMemberCompletions(analysis, document, position) {
   const items = unsettled.map((member) => ({
     label: member.name,
     kind: "property",
-    detail: `${sourceTypeText(member.member.type)} \u2014 required`,
+    detail: `${neoSourceTypeText(member.member.type)} \u2014 required`,
     insertText: `${member.name} = `,
     // Required members sort ahead of defaulted ones: they are the only entries
     // whose absence is a diagnostic.
@@ -143369,7 +143801,7 @@ function projectInitializerMemberCompletions(analysis, document, position) {
     items.push({
       label: member.name,
       kind: "property",
-      detail: sourceTypeText(member.type),
+      detail: neoSourceTypeText(member.type),
       insertText: `${member.name} = `,
       sortText: `1${member.name}`
     });
@@ -143407,10 +143839,6 @@ function functionParameterLabel(parameter4) {
   const suffix = parameter4.defaultValue === void 0 ? "" : ` = ${parameter4.defaultValue.text}`;
   return `${parameter4.type.name} ${parameter4.name}${suffix}`;
 }
-function sourceTypeText(type) {
-  const args = type.typeArguments.length > 0 ? `<${type.typeArguments.map(sourceTypeText).join(", ")}>` : "";
-  return `${type.name}${args}${type.nullable ? "?" : ""}`;
-}
 function projectConstructionIndex(analysis) {
   const cached = CONSTRUCTION_INDEX_CACHE.get(analysis);
   if (cached) return cached;
@@ -143688,9 +144116,10 @@ ${resolved.symbol.documentation}` : "";
 ID: \`${resolved.symbol.id}\`` : "\n\nPending ID";
   const detail = resolved.symbol.detail ? `: \`${resolved.symbol.detail}\`` : "";
   const contract = resolved.symbol.kind === "class" ? projectConstructionContractMarkdown(analysis, resolved.symbol.name) : "";
+  const lifecycle = resolved.symbol.kind === "member" && resolved.symbol.callable === true && resolved.symbol.static !== true && analysis.documents.get(resolved.symbol.location.uri)?.kind !== "flow" ? lifecycleHoverMarkdown(analysis, resolved.symbol.name) : "";
   return {
     range: resolved.token.range,
-    markdown: `**${resolved.symbol.kind}** \`${resolved.symbol.name}\`${detail}${owner}${documentation}${contract}${id2}`
+    markdown: `**${resolved.symbol.kind}** \`${resolved.symbol.name}\`${detail}${owner}${documentation}${lifecycle}${contract}${id2}`
   };
 }
 function projectBuiltinSymbolAt(document, position) {
@@ -143731,7 +144160,7 @@ Construct with \`new(${parameters})\` \u2014 this class declares a required cons
   const lines = [];
   if (required2.length > 0) {
     const members = required2.map(
-      (member) => `\`${sourceTypeText(member.member.type)} ${member.name}\``
+      (member) => `\`${neoSourceTypeText(member.member.type)} ${member.name}\``
     ).join(", ");
     lines.push(`Every construction path must settle ${members}.`);
   }
@@ -144895,7 +145324,7 @@ function declarationConstructorParameters(declaration) {
 }
 function sourceParameterProjection(parameter4) {
   return {
-    type: sourceTypeText(parameter4.type),
+    type: neoSourceTypeText(parameter4.type),
     name: parameter4.name,
     ...parameter4.defaultValue === void 0 ? {} : { defaultText: parameter4.defaultValue.text }
   };
@@ -145006,6 +145435,8 @@ var init_project_source_language_features = __esm({
     init_language_spec();
     init_project_source_semantics();
     init_project_source_variants();
+    init_project_source_lifecycle_editor();
+    init_project_source_ast();
     init_project();
     init_project_source_semantics();
     init_project_source_settlement();
@@ -145127,7 +145558,7 @@ function localValueRefactorings(analysis, document, range2) {
                 start: { line: 0, character: 0 },
                 end: { line: 0, character: 0 }
               },
-              newText: `${typeText2(type)} ${name} = ${selected};
+              newText: `${neoSourceTypeText(type)} ${name} = ${selected};
 `
             }
           ]
@@ -145136,9 +145567,6 @@ function localValueRefactorings(analysis, document, range2) {
     }
   ];
 }
-function typeText2(type) {
-  return type.name + (type.typeArguments.length === 0 ? "" : `<${type.typeArguments.map(typeText2).join(", ")}>`) + (type.nullable ? "?" : "");
-}
 function withoutValueIdentities(text) {
   const tokens = lex(text).roots.filter((token) => token.kind !== "comment");
   const removals = [];
@@ -145215,6 +145643,7 @@ var init_project_local_value_refactorings = __esm({
     init_project_local_values();
     init_project_source_language_features();
     init_source_text();
+    init_project_source_ast();
   }
 });
 
@@ -146143,6 +146572,7 @@ var init_service = __esm({
     init_project_source_identifiers();
     init_project_source_analysis();
     init_project_source_construction_quick_fixes();
+    init_project_source_lifecycle_editor();
     init_project_source_reference_family();
     init_project_source_language_features();
     init_project_source_tokens();
@@ -146460,6 +146890,14 @@ var init_service = __esm({
             actions.push(
               ...projectConstructionQuickFixes(project, state.document, diagnostic)
             );
+            actions.push(
+              ...projectLifecycleQuickFixes(
+                project,
+                state.document,
+                diagnostic,
+                (name) => findTypeDeclaration(project, name)
+              )
+            );
           }
           actions.push(...spellingQuickFixes(state.document, diagnostic));
           const edit = quickFixFor(state.document, diagnostic);
@@ -156206,7 +156644,7 @@ There is no --keep-current: preserving current semantic state defines flatten.
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.command === "--version") {
-    console.log("0.65.1");
+    console.log("0.66.0");
     return;
   }
   if (args.command === null || args.command === "help" || args.command === "--help" || args.command === "-h") {

package/dist/test-worker.mjs

@@ -2124,7 +2124,8 @@ var SystemProtectionKind = {
   DialogueMemoryContainer: "dialogueMemoryContainer",
   DialoguePriorityDefault: "dialoguePriorityDefault",
   PolicyImmutable: "policyImmutable",
-  PolicyDeleteBlocked: "policyDeleteBlocked"
+  PolicyDeleteBlocked: "policyDeleteBlocked",
+  ScriptRuntime: "scriptRuntime"
 };
 function isWithId(value) {
   return typeof value?.id === "string";
@@ -2141,7 +2142,7 @@ function isEpochMillis(value) {
   return Number.isFinite(value);
 }
 function isSystemProtectionKind(value) {
-  return value === SystemProtectionKind.WorldAuthoring || value === SystemProtectionKind.DialogueMemorySchema || value === SystemProtectionKind.DialogueMemoryContainer || value === SystemProtectionKind.DialoguePriorityDefault || value === SystemProtectionKind.PolicyImmutable || value === SystemProtectionKind.PolicyDeleteBlocked;
+  return value === SystemProtectionKind.WorldAuthoring || value === SystemProtectionKind.DialogueMemorySchema || value === SystemProtectionKind.DialogueMemoryContainer || value === SystemProtectionKind.DialoguePriorityDefault || value === SystemProtectionKind.PolicyImmutable || value === SystemProtectionKind.PolicyDeleteBlocked || value === SystemProtectionKind.ScriptRuntime;
 }
 function isSystemMetadata(value) {
   const v = value;
@@ -44835,6 +44836,14 @@ var SYSTEM_PROTECTION_RULES = {
     disallow: [SystemDisallowedOperation.DeleteRecord],
     reasonKey: "systemProtection.reasons.policyDeleteBlocked",
     serverReason: "System default policy may be edited but must keep one default row."
+  },
+  [SystemProtectionKind.ScriptRuntime]: {
+    disallow: [
+      SystemDisallowedOperation.EditRecord,
+      SystemDisallowedOperation.DeleteRecord
+    ],
+    reasonKey: "systemProtection.reasons.scriptRuntime",
+    serverReason: "Lifecycle interface the Neo Compose script runtime calls."
   }
 };
 
@@ -46080,7 +46089,8 @@ function isSchemaSystemMetadata(value) {
     "dialogueMemoryContainer",
     "dialoguePriorityDefault",
     "policyImmutable",
-    "policyDeleteBlocked"
+    "policyDeleteBlocked",
+    "scriptRuntime"
   ]);
   const worlds = /* @__PURE__ */ new Set([
     "cellPattern",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.65.1",
+  "version": "0.66.0",
   "description": "Neo Compose native project-source CLI with bidirectional sync.",
   "license": "MIT",
   "type": "module",

package/skills/neocompose-cli/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   `@neocompose/cli` or `node cli/bin/neo.mjs` in the neo-compose repository.
 ---
 
-<!-- reviewed-through-cli: 0.65.1 -->
+<!-- reviewed-through-cli: 0.66.0 -->
 
 # Neo Compose CLI
 

package/skills/neocompose-cli/references/cli-development.md

@@ -110,7 +110,7 @@ wrappers.
 The marker near the top of `SKILL.md` must exactly match the package version:
 
 ```html
-<!-- reviewed-through-cli: 0.65.1 -->
+<!-- reviewed-through-cli: 0.66.0 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale

package/skills/neocompose-cli/references/declarations-and-construction.md

@@ -197,6 +197,16 @@ itself; both are durable writes deduplicated by target identity, so
 re-running a subscription cannot double-subscribe. Invoke it as a statement —
 an action is never a value, never a return type, and never assigned with `=`.
 
+Implement a system lifecycle interface to run code when the runtime does.
+`INeoOnLoad` and `INeoOnUnload` run when an instance becomes live and when it
+stops being live. The `INeoUnity*` interfaces, such as `INeoUnityUpdate` and
+`INeoUnityOnTriggerEnter2D`, run for a rendered `NeoObjectBase` in play mode.
+Their member names, such as `OnLoad` and `Update`, are reserved: declare one
+only as the public, immediate instance method that implements its interface,
+and never mark it `@effect`. Subscribe Session actions in `OnLoad` and remove
+them in `OnUnload`. React to data changes with `@effect`, and keep `Update`
+for work that really happens every frame.
+
 Keep generic project relations as typed top-level declarations in
 `Relations.neo`. Let the compiler derive identities for owned descriptors and
 concrete generic bindings.