@forgeax/engine-ecs 0.0.0-dev.8d955ade1c79

package/dist/internal.mjs

@@ -0,0 +1,479 @@
+import { err, ok } from '@forgeax/engine-types';
+
+// src/component.ts
+
+// src/component-schema.ts
+var COMPONENT_REGISTRY = /* @__PURE__ */ Symbol.for("forgeax.ecs.componentRegistry");
+var globalSymbols = globalThis;
+var definitions = globalSymbols[COMPONENT_REGISTRY] ?? (() => {
+  const registry = { definitions: /* @__PURE__ */ new WeakMap() };
+  globalSymbols[COMPONENT_REGISTRY] = registry;
+  return registry;
+})();
+function registerComponentDefinition(component, definition) {
+  definitions.definitions.set(component, definition);
+}
+function componentDefinition(component) {
+  const definition = definitions.definitions.get(component);
+  if (definition === void 0) {
+    throw new Error(`Component definition missing for '${component.name}'.`);
+  }
+  return definition;
+}
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object" && typeof value !== "function") {
+    return value;
+  }
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+    return value;
+  }
+  const object = value;
+  for (const key of Reflect.ownKeys(object)) {
+    const child = object[key];
+    if (child !== null && (typeof child === "object" || typeof child === "function")) {
+      deepFreeze(child);
+    }
+  }
+  return Object.freeze(value);
+}
+function assertComponentStorage(value) {
+  if (value !== "table" && value !== "sparse") {
+    throw new Error(`Unsupported component storage '${value}'. Expected 'table' or 'sparse'.`);
+  }
+}
+
+// src/errors.ts
+var SchemaUnsupportedFieldError = class extends Error {
+  name = "SchemaUnsupportedFieldError";
+  code = "schema-unsupported-field";
+  hint;
+  constructor(fieldName, fieldType) {
+    let hint = "Supported types: f32 / f64 / i32 / u32 / i16 / u16 / i8 / u8 / bool / enum / ref.";
+    if (fieldType.startsWith("handle<") && fieldType.endsWith(">")) {
+      const tag = fieldType.slice(7, -1);
+      hint = `'handle<${tag}>' was removed in feat-20260614 M5; use 'shared<${tag}>' instead. The brand and storage layout are unchanged; only the keyword + write-barrier dispatch (SharedRefStore retain/release) is new.`;
+    } else if (fieldType.startsWith("ref<") && fieldType.endsWith(">")) {
+      const tag = fieldType.slice(4, -1);
+      hint = `'ref<${tag}>' was renamed in feat-20260614 M1; use 'unique<${tag}>' instead. The brand and storage layout are unchanged; the dispatch still routes through UniqueRefStore (single-holder direct release).`;
+    }
+    super(
+      `Schema field "${fieldName}" has unsupported type "${fieldType}".
+  field: ${fieldName}
+  type: ${fieldType}
+  hint: ${hint}`
+    );
+    this.hint = hint;
+  }
+};
+var SparseStorageRequiresTagError = class extends Error {
+  name = "SparseStorageRequiresTagError";
+  code = "sparse-storage-requires-tag";
+  expected = "sparse components have an empty schema and no relationship metadata";
+  hint = "remove all fields and relationship metadata, or use storage: table";
+  detail;
+  constructor(componentName) {
+    super(
+      `Sparse component "${componentName}" must be a zero-field, non-relationship tag.
+  component: ${componentName}
+  hint: remove all fields and relationship metadata, or use storage: table`
+    );
+    this.detail = { componentName };
+  }
+};
+var ManagedArrayElementTypeNotAllowedError = class extends Error {
+  name = "ManagedArrayElementTypeNotAllowedError";
+  code = "managed-array-element-type-not-allowed";
+  hint;
+  expected;
+  detail;
+  constructor(fieldName, elementType) {
+    const hint = `array<T> element type must be a scalar (f32/f64/i32/u32/i16/u16/i8/u8/bool/enum/ref) or entity. ref<X> / handle<X> / buffer:N / nested array<...> are forbidden on field "${fieldName}".`;
+    const expected = "element type in {scalar | entity}";
+    super(
+      `managed-array: element type not allowed.
+  code: managed-array-element-type-not-allowed
+  field: ${fieldName}
+  elementType: ${elementType}
+  expected: ${expected}
+  hint: ${hint}`
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { fieldName, elementType, hint };
+  }
+};
+
+// src/component.ts
+var FIELD_SIZE_BYTES = {
+  f32: 4,
+  f64: 8,
+  i32: 4,
+  u32: 4,
+  i16: 2,
+  u16: 2,
+  i8: 1,
+  u8: 1,
+  bool: 1,
+  enum: 4,
+  ref: 4
+};
+function fieldTypeToMetaKey(fieldType) {
+  if (fieldType === "entity" || fieldType === "string" || fieldType === "buffer") {
+    return fieldType;
+  }
+  if (fieldType.startsWith("unique<") && fieldType.endsWith(">")) return "ref";
+  if (fieldType.startsWith("shared<") && fieldType.endsWith(">")) return "shared";
+  if (fieldType.startsWith("buffer<") && fieldType.endsWith(">")) return "buffer";
+  if (fieldType.startsWith("array<") && fieldType.endsWith(">")) return "array";
+  if (TYPE_METADATA[fieldType] !== void 0) return fieldType;
+  return null;
+}
+function isManagedField(fieldType) {
+  return TYPE_METADATA[fieldTypeToMetaKey(fieldType) ?? ""]?.isManaged ?? false;
+}
+function isManagedBufferField(fieldType) {
+  return TYPE_METADATA[fieldTypeToMetaKey(fieldType) ?? ""]?.isBuffer ?? false;
+}
+function isEntityField(fieldType) {
+  return TYPE_METADATA[fieldTypeToMetaKey(fieldType) ?? ""]?.isEntityRef ?? false;
+}
+function isManagedArrayField(fieldType) {
+  return TYPE_METADATA[fieldTypeToMetaKey(fieldType) ?? ""]?.isArray ?? false;
+}
+var MANAGED_ARRAY_ELEMENT_TYPES = /* @__PURE__ */ new Set([
+  "f32",
+  "f64",
+  "i32",
+  "u32",
+  "i16",
+  "u16",
+  "i8",
+  "u8",
+  "bool",
+  "enum",
+  "ref",
+  "entity"
+]);
+function isValidArrayElementType(elementType) {
+  if (MANAGED_ARRAY_ELEMENT_TYPES.has(elementType)) return true;
+  if (elementType.startsWith("shared<") && elementType.endsWith(">") && elementType.length > 9)
+    return true;
+  return false;
+}
+function parseManagedArraySchema(fieldType) {
+  if (!fieldType.startsWith("array<") || !fieldType.endsWith(">")) return null;
+  const inner = fieldType.slice(6, -1);
+  const commaIdx = inner.indexOf(",");
+  if (commaIdx === -1) {
+    if (!isValidArrayElementType(inner)) return null;
+    return { elementType: inner, length: void 0 };
+  }
+  const head = inner.slice(0, commaIdx).trim();
+  const tail = inner.slice(commaIdx + 1).trim();
+  if (!isValidArrayElementType(head)) return null;
+  if (!/^[1-9]\d*$/.test(tail)) return null;
+  return { elementType: head, length: Number.parseInt(tail, 10) };
+}
+function bufferFieldByteLength(fieldType) {
+  if (!fieldType.startsWith("buffer<") || !fieldType.endsWith(">")) return Number.NaN;
+  const tail = fieldType.slice(7, -1);
+  if (!/^[1-9]\d*$/.test(tail)) return Number.NaN;
+  return Number.parseInt(tail, 10);
+}
+function isSchemaVocabKeyword(s) {
+  if (s === "string") return true;
+  if (s === "entity") return true;
+  if (s === "buffer") return true;
+  if (s.startsWith("buffer<") && s.endsWith(">")) {
+    const tail = s.slice(7, -1);
+    return /^[1-9]\d*$/.test(tail);
+  }
+  if (s.startsWith("unique<") && s.endsWith(">")) {
+    return /^\w+$/.test(s.slice(7, -1));
+  }
+  if (s.startsWith("shared<") && s.endsWith(">")) {
+    return /^\w+$/.test(s.slice(7, -1));
+  }
+  if (s.startsWith("array<") && s.endsWith(">")) {
+    return parseManagedArraySchema(s) !== null;
+  }
+  return false;
+}
+var COMPONENT_OWNER_REGISTRY = /* @__PURE__ */ Symbol.for("forgeax.ecs.componentOwnerRegistry");
+var ownerSymbols = globalThis;
+var ownerRegistry = ownerSymbols[COMPONENT_OWNER_REGISTRY] ?? (() => {
+  const registry = {
+    nextId: 1,
+    ids: /* @__PURE__ */ new WeakMap(),
+    schemas: /* @__PURE__ */ new WeakMap()
+  };
+  ownerSymbols[COMPONENT_OWNER_REGISTRY] = registry;
+  return registry;
+})();
+var entityDefinitionSeen = false;
+var componentDefinedBeforeEntity = false;
+function isComponentDefinitionOrderValid() {
+  return !componentDefinedBeforeEntity;
+}
+function componentId(component) {
+  const id = ownerRegistry.ids.get(component);
+  if (id === void 0) throw new Error(`Component identity missing for '${component.name}'.`);
+  return id;
+}
+function componentSchema(component) {
+  const schema = ownerRegistry.schemas.get(component);
+  if (schema === void 0) throw new Error(`Component schema missing for '${component.name}'.`);
+  return schema;
+}
+var VIEW_CTORS = {
+  f32: Float32Array,
+  f64: Float64Array,
+  i32: Int32Array,
+  u32: Uint32Array,
+  i16: Int16Array,
+  u16: Uint16Array,
+  i8: Int8Array,
+  u8: Uint8Array,
+  bool: Uint8Array,
+  enum: Uint32Array,
+  ref: Uint32Array
+};
+function scalarRow(t) {
+  return {
+    byteSize: FIELD_SIZE_BYTES[t],
+    viewCtor: VIEW_CTORS[t],
+    storage: t,
+    isScalar: true,
+    // The scalar `ref` shares its key with the vocab `ref<T>` family; mark
+    // it as managed so the single row covers both.
+    isManaged: t === "ref",
+    isBuffer: false,
+    isEntityRef: false,
+    isArray: false
+  };
+}
+var TYPE_METADATA = Object.freeze({
+  f32: scalarRow("f32"),
+  f64: scalarRow("f64"),
+  i32: scalarRow("i32"),
+  u32: scalarRow("u32"),
+  i16: scalarRow("i16"),
+  u16: scalarRow("u16"),
+  i8: scalarRow("i8"),
+  u8: scalarRow("u8"),
+  bool: scalarRow("bool"),
+  enum: scalarRow("enum"),
+  ref: scalarRow("ref"),
+  entity: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: false,
+    isBuffer: false,
+    isEntityRef: true,
+    isArray: false
+  },
+  string: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: true,
+    isBuffer: false,
+    isEntityRef: false,
+    isArray: false
+  },
+  buffer: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: false,
+    isBuffer: true,
+    isEntityRef: false,
+    isArray: false
+  },
+  // feat-20260614-ecs-shared-component-and-unique-rename M3 (plan-strategy
+  // D-3): independent `'shared'` row, NOT a reuse of the `'ref'` (post-M2:
+  // `'unique<T>'` family) row. `isManaged: true` so write-barrier dispatch
+  // routes shared<T> fields through release on despawn / removeComponent /
+  // set-overwrite, but the M4 sub-dispatch in releaseManagedFieldOnRow will
+  // separate shared (rc--) from unique (direct slot drop) using the
+  // fieldType.startsWith('shared<') predicate. Keeping the meta key
+  // independent preserves the "meta key = release semantics" invariant
+  // (architecture-principles.md #1 SSOT).
+  shared: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: true,
+    isBuffer: false,
+    isEntityRef: false,
+    isArray: false
+  },
+  array: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: false,
+    isBuffer: false,
+    isEntityRef: false,
+    isArray: true
+  }
+});
+function fieldSpecType(fieldName, spec) {
+  if (typeof spec === "string") return spec;
+  const t = spec.type;
+  if (typeof t !== "string") {
+    throw new SchemaUnsupportedFieldError(
+      fieldName,
+      `<field-descriptor missing 'type'> (expected { type, default?, meta? })`
+    );
+  }
+  return t;
+}
+function defineComponent(name, fields, options) {
+  const storage = options?.storage ?? "table";
+  assertComponentStorage(storage);
+  if (storage === "sparse" && Object.keys(fields).length !== 0) {
+    throw new SparseStorageRequiresTagError(name);
+  }
+  const schema = {};
+  const reflectedFields = {};
+  const collectedMeta = {};
+  const collectedDefaults = {};
+  for (const fieldName of Object.keys(fields)) {
+    const spec = fields[fieldName];
+    const fieldType = fieldSpecType(fieldName, spec);
+    let arrayMeta;
+    if (TYPE_METADATA[fieldType]?.isScalar === true) ; else if (fieldType === "string") ; else if (fieldType.startsWith("array<") && fieldType.endsWith(">")) {
+      const parsed = parseManagedArraySchema(fieldType);
+      if (parsed === null) {
+        const elementType = fieldType.slice(6, -1);
+        throw new ManagedArrayElementTypeNotAllowedError(fieldName, elementType);
+      }
+      arrayMeta = deepFreeze(
+        parsed.length === void 0 ? { elementType: parsed.elementType } : { elementType: parsed.elementType, length: parsed.length }
+      );
+    } else if (!isSchemaVocabKeyword(fieldType)) {
+      throw new SchemaUnsupportedFieldError(fieldName, fieldType);
+    }
+    schema[fieldName] = fieldType;
+    const row = {
+      type: fieldType
+    };
+    if (typeof spec !== "string") {
+      const desc = spec;
+      if ("default" in desc) {
+        row.default = desc.default;
+        collectedDefaults[fieldName] = desc.default;
+      }
+      if (desc.shape !== void 0) row.shape = desc.shape;
+      if (desc.meta !== void 0) {
+        Object.assign(collectedMeta, desc.meta);
+      }
+      if (desc.transient !== void 0) row.transient = desc.transient;
+      if (desc.labels !== void 0) row.labels = deepFreeze({ ...desc.labels });
+    }
+    if (arrayMeta !== void 0) row.arrayMeta = arrayMeta;
+    reflectedFields[fieldName] = Object.freeze(row);
+  }
+  if (name === "Entity") {
+    entityDefinitionSeen = true;
+  } else if (!entityDefinitionSeen) {
+    componentDefinedBeforeEntity = true;
+  }
+  const id = name === "Entity" ? 0 : ownerRegistry.nextId++;
+  const frozenDefaults = Object.keys(collectedDefaults).length === 0 ? void 0 : deepFreeze(collectedDefaults);
+  if (options?.meta !== void 0) {
+    Object.assign(collectedMeta, options.meta);
+  }
+  const frozenSchema = deepFreeze(schema);
+  const frozenFields = deepFreeze(reflectedFields);
+  const meta = collectedMeta;
+  const token = Object.freeze({ name, fields: frozenFields, storage });
+  ownerRegistry.ids.set(token, id);
+  ownerRegistry.schemas.set(token, frozenSchema);
+  registerComponentDefinition(token, {
+    fields: frozenFields,
+    defaults: frozenDefaults,
+    policy: { transient: options?.transient ?? false, meta }
+  });
+  return Object.freeze(token);
+}
+var ComponentInUseError = class extends Error {
+  name = "ComponentInUseError";
+  code = "component-in-use";
+  expected = "the component to have no live entity or scheduled-system references";
+  hint = "Remove owning systems and component values before disposing the registration lease.";
+  detail;
+  constructor(componentName) {
+    super(`Component ${componentName} is still in use.`);
+    this.detail = { componentName };
+  }
+};
+var ComponentNameConflictError = class extends Error {
+  name = "ComponentNameConflictError";
+  code = "component-name-conflict";
+  expected = "one component token per name in a World";
+  hint = "Use the token already registered in this World or choose a distinct component name.";
+  detail;
+  constructor(componentName) {
+    super(`Component ${componentName} is already registered with a different token.`);
+    this.detail = { componentName };
+  }
+};
+var ComponentCatalog = class {
+  constructor(inUse) {
+    this.inUse = inUse;
+  }
+  inUse;
+  registrations = /* @__PURE__ */ new Map();
+  register(component) {
+    const current = this.registrations.get(component.name);
+    if (current !== void 0 && current.component !== component) {
+      return err(new ComponentNameConflictError(component.name));
+    }
+    if (current === void 0) {
+      this.registrations.set(component.name, { component, owners: 1 });
+    } else {
+      current.owners += 1;
+    }
+    let active = true;
+    return ok({
+      component,
+      dispose: () => {
+        if (!active) return ok(void 0);
+        const registration = this.registrations.get(component.name);
+        if (registration === void 0 || registration.component !== component) {
+          active = false;
+          return ok(void 0);
+        }
+        if (registration.owners > 1) {
+          registration.owners -= 1;
+          active = false;
+          return ok(void 0);
+        }
+        if (this.inUse(component)) return err(new ComponentInUseError(component.name));
+        this.registrations.delete(component.name);
+        active = false;
+        return ok(void 0);
+      }
+    });
+  }
+  resolve(name) {
+    return this.registrations.get(name)?.component;
+  }
+  entries() {
+    return new Map(
+      [...this.registrations].map(([name, registration]) => [name, registration.component])
+    );
+  }
+};
+
+export { ComponentCatalog, ComponentInUseError, ComponentNameConflictError, MANAGED_ARRAY_ELEMENT_TYPES, TYPE_METADATA, bufferFieldByteLength, componentDefinition, componentId, componentSchema, defineComponent, fieldTypeToMetaKey, isComponentDefinitionOrderValid, isEntityField, isManagedArrayField, isManagedBufferField, isManagedField, isSchemaVocabKeyword, parseManagedArraySchema };
+//# sourceMappingURL=internal.mjs.map
+//# sourceMappingURL=internal.mjs.map