@helix3/helix-cli 0.1.4-helix3.24

package/vendor/ability-manifest.mjs

@@ -0,0 +1,558 @@
+// @helix/humanoid-character@0.2.2 — ability.json validator (frozen C3 contract).
+// Generated by emit-schemas; vendored by @hypersoniclabs/helix-cli. Do not edit; changes require ability-v2.
+
+// src/core/config/paths.ts
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/core/config/schema.ts
+function levenshtein(a, b) {
+  const prev = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0];
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = prev[j];
+      prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+      diag = tmp;
+    }
+  }
+  return prev[b.length];
+}
+function nearestKey(key, candidates) {
+  let best;
+  let bestDist = Infinity;
+  for (const candidate of candidates) {
+    const dist = levenshtein(key.toLowerCase(), candidate.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = candidate;
+    }
+  }
+  return best !== void 0 && bestDist <= Math.max(2, Math.floor(key.length * 0.4)) ? best : void 0;
+}
+
+// src/bundle/abilityManifest.ts
+var ABILITY_ID_PATTERN = "^[a-z0-9](?:[a-z0-9-]{1,48})[a-z0-9]$";
+var SEMVER_PATTERN = "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z.-]+)?$";
+var SYSTEM_RANGE_PATTERN = "^[\\^~]?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z.-]+)?$";
+var SKELETON_PATTERN = "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?@(0|[1-9]\\d*)$";
+var ENTRY_PATH_PATTERN = "^(?!/)(?!.*\\.\\.)[A-Za-z0-9._/-]+\\.m?js$";
+var SCHEMA_PATH_PATTERN = "^(?!/)(?!.*\\.\\.)[A-Za-z0-9._/-]+\\.json$";
+var CLIP_SRC_PATTERN = "^(?!/)(?!.*\\.\\.)[A-Za-z0-9._/-]+\\.gl(?:b|tf)$";
+var CHANNEL_NAME_PATTERN = "^[a-z][a-z0-9-]*$";
+var LOCAL_NAME_PATTERN = "^[A-Za-z0-9_][A-Za-z0-9_-]*$";
+var CONDITION_PARAM_PATTERN = "^[A-Za-z][A-Za-z0-9_.-]*$";
+var RESERVED_CONFIG_PREFIXES = ["character", "abilities"];
+var CONDITION_OPS = ["==", "!=", ">", "<", ">=", "<="];
+var ACTIVATION_MODES = ["always", "manual", "contextual"];
+var ACTIVATION_STYLES = ["toggle", "hold"];
+var AbilityManifestError = class extends Error {
+  issues;
+  constructor(issues) {
+    super(`ability.json is invalid:
+${issues.map((i) => `  ${i.path === "" ? "(root)" : i.path}: ${i.message}`).join("\n")}`);
+    this.name = "AbilityManifestError";
+    this.issues = issues;
+  }
+};
+function typeName(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function checkString(value, path, issues, rule = {}) {
+  if (typeof value !== "string" || value.length === 0) {
+    issues.push({ path, message: `must be a non-empty string (got ${typeName(value)})` });
+    return void 0;
+  }
+  if (rule.pattern !== void 0 && !new RegExp(rule.pattern).test(value)) {
+    issues.push({ path, message: `'${value}' is not ${rule.hint ?? `a match for ${rule.pattern}`}` });
+    return void 0;
+  }
+  return value;
+}
+function checkQualifiedName(value, path, issues, abilityId, what) {
+  if (typeof value !== "string" || value.length === 0) {
+    issues.push({ path, message: `must be a non-empty string (got ${typeName(value)})` });
+    return void 0;
+  }
+  if (abilityId === void 0) return value;
+  const prefix = `${abilityId}.`;
+  if (!value.startsWith(prefix)) {
+    issues.push({ path, message: `${what} '${value}' must be namespaced '${prefix}<name>' (names carry the ability id)` });
+    return void 0;
+  }
+  const local = value.slice(prefix.length);
+  if (!new RegExp(LOCAL_NAME_PATTERN).test(local)) {
+    issues.push({ path, message: `${what} '${value}': the part after '${prefix}' must match ${LOCAL_NAME_PATTERN}` });
+    return void 0;
+  }
+  return value;
+}
+function checkCondition(value, path, issues) {
+  if (!Array.isArray(value) || value.length !== 3) {
+    issues.push({ path, message: `must be a [param, op, value] triple (got ${typeName(value)})` });
+    return;
+  }
+  const [param, op, operand] = value;
+  if (typeof param !== "string" || !new RegExp(CONDITION_PARAM_PATTERN).test(param)) {
+    issues.push({ path: `${path}[0]`, message: `must be a blackboard parameter name (got ${typeName(param)})` });
+  }
+  if (typeof op !== "string" || !CONDITION_OPS.includes(op)) {
+    issues.push({ path: `${path}[1]`, message: `must be one of: ${CONDITION_OPS.join(", ")}` });
+  }
+  if (typeof operand !== "number" && typeof operand !== "boolean") {
+    issues.push({ path: `${path}[2]`, message: `must be a number or boolean (got ${typeName(operand)})` });
+  }
+}
+function checkActivation(value, issues) {
+  if (!isPlainObject(value)) {
+    issues.push({ path: "activation", message: `must be an object with a 'mode' (got ${typeName(value)})` });
+    return;
+  }
+  const mode = value.mode;
+  if (typeof mode !== "string" || !ACTIVATION_MODES.includes(mode)) {
+    issues.push({ path: "activation.mode", message: `must be one of: ${ACTIVATION_MODES.join(", ")}` });
+    return;
+  }
+  const allowed = mode === "always" ? ["mode"] : mode === "manual" ? ["mode", "action", "style"] : ["mode", "when"];
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) issues.push({ path: `activation.${key}`, message: `not a field of mode '${mode}' (allowed: ${allowed.join(", ")})` });
+  }
+  if (mode === "manual") {
+    checkString(value.action, "activation.action", issues);
+    if (typeof value.style !== "string" || !ACTIVATION_STYLES.includes(value.style)) {
+      issues.push({ path: "activation.style", message: `must be one of: ${ACTIVATION_STYLES.join(", ")}` });
+    }
+  } else if (mode === "contextual") {
+    if (!Array.isArray(value.when) || value.when.length === 0) {
+      issues.push({ path: "activation.when", message: `must be a non-empty array of [param, op, value] conditions (got ${typeName(value.when)})` });
+    } else {
+      value.when.forEach((cond, i) => checkCondition(cond, `activation.when[${i}]`, issues));
+    }
+  }
+}
+function checkBindings(value, path, issues) {
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: `must be an object (got ${typeName(value)})` });
+    return;
+  }
+  const stringArray = (v) => Array.isArray(v) && v.every((s) => typeof s === "string" && s.length > 0);
+  const numberArray = (v) => Array.isArray(v) && v.every((n) => typeof n === "number" && Number.isInteger(n) && n >= 0);
+  for (const key of Object.keys(value)) {
+    const v = value[key];
+    switch (key) {
+      case "keys":
+        if (!stringArray(v)) issues.push({ path: `${path}.keys`, message: "must be an array of KeyboardEvent.code strings" });
+        break;
+      case "composite": {
+        if (!isPlainObject(v)) {
+          issues.push({ path: `${path}.composite`, message: "must be an object with up/down/left/right key arrays" });
+          break;
+        }
+        for (const dir of Object.keys(v)) {
+          if (!["up", "down", "left", "right"].includes(dir)) issues.push({ path: `${path}.composite.${dir}`, message: "must be one of: up, down, left, right" });
+          else if (!stringArray(v[dir])) issues.push({ path: `${path}.composite.${dir}`, message: "must be an array of KeyboardEvent.code strings" });
+        }
+        break;
+      }
+      case "mouseButtons":
+      case "gamepadButtons":
+        if (!numberArray(v)) issues.push({ path: `${path}.${key}`, message: "must be an array of non-negative button indices" });
+        break;
+      case "gamepadAxes":
+        if (!numberArray(v) || v.length !== 2) issues.push({ path: `${path}.gamepadAxes`, message: "must be [xAxisIndex, yAxisIndex]" });
+        break;
+      case "deadzone":
+        if (typeof v !== "number" || v < 0 || v >= 1) issues.push({ path: `${path}.deadzone`, message: "must be a number in [0, 1)" });
+        break;
+      default: {
+        const suggestion = nearestKey(key, ["keys", "composite", "mouseButtons", "gamepadButtons", "gamepadAxes", "deadzone"]);
+        issues.push({ path: `${path}.${key}`, message: suggestion !== void 0 ? `unknown binding field \u2014 did you mean "${suggestion}"?` : "unknown binding field" });
+      }
+    }
+  }
+}
+function validateAbilityManifest(value) {
+  const issues = [];
+  if (!isPlainObject(value)) {
+    issues.push({ path: "", message: `ability.json must be a JSON object (got ${typeName(value)})` });
+    return issues;
+  }
+  const knownFields = Object.keys(ABILITY_V1_JSON_SCHEMA.properties);
+  for (const key of Object.keys(value)) {
+    if (!knownFields.includes(key)) {
+      const suggestion = nearestKey(key, knownFields);
+      issues.push({ path: key, message: suggestion !== void 0 ? `unknown field \u2014 did you mean "${suggestion}"?` : `unknown field (allowed: ${knownFields.join(", ")})` });
+    }
+  }
+  if (value.schemaVersion !== 1) {
+    issues.push({ path: "schemaVersion", message: `must be the number 1 \u2014 this validator implements ability-v1 (got ${JSON.stringify(value.schemaVersion)})` });
+  }
+  const id = checkString(value.id, "id", issues, {
+    pattern: ABILITY_ID_PATTERN,
+    hint: "a platform slug (3-50 chars: lowercase letters, digits, hyphens; no leading/trailing hyphen)"
+  });
+  if (id !== void 0 && RESERVED_CONFIG_PREFIXES.includes(id)) {
+    issues.push({ path: "id", message: `'${id}' is a reserved config prefix (reserved: ${RESERVED_CONFIG_PREFIXES.join(", ")})` });
+  }
+  checkString(value.version, "version", issues, { pattern: SEMVER_PATTERN, hint: "a semver version like 1.0.0" });
+  checkString(value.title, "title", issues);
+  if (value.description !== void 0) checkString(value.description, "description", issues);
+  if (!isPlainObject(value.system)) {
+    issues.push({ path: "system", message: `must be the host-system pin { id, version, skeleton } (got ${typeName(value.system)})` });
+  } else {
+    checkString(value.system.id, "system.id", issues, { pattern: ABILITY_ID_PATTERN, hint: "a system slug like 'humanoid-character'" });
+    checkString(value.system.version, "system.version", issues, { pattern: SYSTEM_RANGE_PATTERN, hint: "a semver range like '^1.0.0' (exact, ^, or ~)" });
+    checkString(value.system.skeleton, "system.skeleton", issues, { pattern: SKELETON_PATTERN, hint: "a skeleton standard tag like 'helix-humanoid@1'" });
+    for (const key of Object.keys(value.system)) {
+      if (!["id", "version", "skeleton"].includes(key)) issues.push({ path: `system.${key}`, message: "unknown field (allowed: id, version, skeleton)" });
+    }
+  }
+  if (value.activation === void 0) issues.push({ path: "activation", message: "required \u2014 one of { mode: 'always' | 'manual' | 'contextual' }" });
+  else checkActivation(value.activation, issues);
+  if (value.channels !== void 0) {
+    if (!isPlainObject(value.channels)) {
+      issues.push({ path: "channels", message: `must be an object of { <channel>: { priority } } (got ${typeName(value.channels)})` });
+    } else {
+      for (const [channel, spec] of Object.entries(value.channels)) {
+        if (!new RegExp(CHANNEL_NAME_PATTERN).test(channel)) {
+          issues.push({ path: `channels.${channel}`, message: `channel names must match ${CHANNEL_NAME_PATTERN}` });
+        }
+        if (!isPlainObject(spec) || typeof spec.priority !== "number" || !Number.isFinite(spec.priority) || spec.priority < 0) {
+          issues.push({ path: `channels.${channel}`, message: "must be { priority: <number >= 0> }" });
+        } else {
+          for (const key of Object.keys(spec)) {
+            if (key !== "priority") issues.push({ path: `channels.${channel}.${key}`, message: "unknown field (allowed: priority)" });
+          }
+        }
+      }
+    }
+  }
+  const actionIds = [];
+  if (value.actions !== void 0) {
+    if (!Array.isArray(value.actions)) {
+      issues.push({ path: "actions", message: `must be an array of { id, kind?, defaultBinding? } (got ${typeName(value.actions)})` });
+    } else {
+      value.actions.forEach((action, i) => {
+        const path = `actions[${i}]`;
+        if (!isPlainObject(action)) {
+          issues.push({ path, message: `must be an object (got ${typeName(action)})` });
+          return;
+        }
+        const actionId = checkQualifiedName(action.id, `${path}.id`, issues, id, "action");
+        if (actionId !== void 0) {
+          if (actionIds.includes(actionId)) issues.push({ path: `${path}.id`, message: `duplicate action id '${actionId}'` });
+          actionIds.push(actionId);
+        }
+        if (action.kind !== void 0 && (typeof action.kind !== "string" || !["button", "toggle", "vec2"].includes(action.kind))) {
+          issues.push({ path: `${path}.kind`, message: "must be one of: button, toggle, vec2" });
+        }
+        if (action.defaultBinding !== void 0) checkBindings(action.defaultBinding, `${path}.defaultBinding`, issues);
+        for (const key of Object.keys(action)) {
+          if (!["id", "kind", "defaultBinding"].includes(key)) issues.push({ path: `${path}.${key}`, message: "unknown field (allowed: id, kind, defaultBinding)" });
+        }
+      });
+    }
+  }
+  const clipNames = [];
+  const additiveRefs = [];
+  if (value.clips !== void 0) {
+    if (!Array.isArray(value.clips)) {
+      issues.push({ path: "clips", message: `must be an array of { name, src, ... } (got ${typeName(value.clips)})` });
+    } else {
+      value.clips.forEach((clip, i) => {
+        const path = `clips[${i}]`;
+        if (!isPlainObject(clip)) {
+          issues.push({ path, message: `must be an object (got ${typeName(clip)})` });
+          return;
+        }
+        const name = checkQualifiedName(clip.name, `${path}.name`, issues, id, "clip");
+        if (name !== void 0) {
+          if (clipNames.includes(name)) issues.push({ path: `${path}.name`, message: `duplicate clip name '${name}'` });
+          clipNames.push(name);
+        }
+        checkString(clip.src, `${path}.src`, issues, { pattern: CLIP_SRC_PATTERN, hint: "a bundle-relative .glb/.gltf path (no leading '/', no '..')" });
+        if (clip.loop !== void 0 && typeof clip.loop !== "boolean") issues.push({ path: `${path}.loop`, message: "must be a boolean" });
+        if (clip.strideSpeed !== void 0 && clip.strideSpeed !== null && typeof clip.strideSpeed !== "number") {
+          issues.push({ path: `${path}.strideSpeed`, message: "must be a number (m/s) or null for non-travelling clips" });
+        }
+        if (clip.additive !== void 0 && typeof clip.additive !== "boolean") issues.push({ path: `${path}.additive`, message: "must be a boolean" });
+        if (clip.additiveRef !== void 0) {
+          const ref = checkQualifiedName(clip.additiveRef, `${path}.additiveRef`, issues, id, "clip reference");
+          if (ref !== void 0) additiveRefs.push([i, ref]);
+        }
+        if (clip.direction !== void 0 && typeof clip.direction !== "number") issues.push({ path: `${path}.direction`, message: "must be a number (deg, gait-F = 0)" });
+        for (const key of Object.keys(clip)) {
+          if (!["name", "src", "loop", "strideSpeed", "additive", "additiveRef", "direction"].includes(key)) {
+            const suggestion = nearestKey(key, ["name", "src", "loop", "strideSpeed", "additive", "additiveRef", "direction"]);
+            issues.push({ path: `${path}.${key}`, message: suggestion !== void 0 ? `unknown field \u2014 did you mean "${suggestion}"?` : "unknown field" });
+          }
+        }
+      });
+      for (const [i, ref] of additiveRefs) {
+        if (!clipNames.includes(ref)) {
+          issues.push({ path: `clips[${i}].additiveRef`, message: `'${ref}' does not name a clip in this manifest (clips: ${clipNames.join(", ") || "none"})` });
+        }
+      }
+    }
+  }
+  if (isPlainObject(value.activation) && value.activation.mode === "manual" && typeof value.activation.action === "string") {
+    if (!actionIds.includes(value.activation.action)) {
+      issues.push({
+        path: "activation.action",
+        message: `'${value.activation.action}' is not declared in actions (declared: ${actionIds.join(", ") || "none"})`
+      });
+    }
+  }
+  checkString(value.configSchema, "configSchema", issues, { pattern: SCHEMA_PATH_PATTERN, hint: "a bundle-relative .json path (no leading '/', no '..')" });
+  checkString(value.entry, "entry", issues, { pattern: ENTRY_PATH_PATTERN, hint: "a bundle-relative .js/.mjs path (no leading '/', no '..')" });
+  return issues;
+}
+function parseAbilityManifest(value) {
+  const issues = validateAbilityManifest(value);
+  if (issues.length > 0) throw new AbilityManifestError(issues);
+  return value;
+}
+function parseSemver(version) {
+  const match = new RegExp(SEMVER_PATTERN).exec(version);
+  if (match === null) return null;
+  const prerelease = version.includes("-") ? version.slice(version.indexOf("-") + 1).split(".") : [];
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), prerelease };
+}
+function compareSemver(a, b) {
+  if (a.major !== b.major) return a.major < b.major ? -1 : 1;
+  if (a.minor !== b.minor) return a.minor < b.minor ? -1 : 1;
+  if (a.patch !== b.patch) return a.patch < b.patch ? -1 : 1;
+  if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+    return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length === 0 ? 1 : -1;
+  }
+  for (let i = 0; i < Math.max(a.prerelease.length, b.prerelease.length); i++) {
+    const ai = a.prerelease[i];
+    const bi = b.prerelease[i];
+    if (ai === void 0) return -1;
+    if (bi === void 0) return 1;
+    const an = /^\d+$/.test(ai) ? Number(ai) : null;
+    const bn = /^\d+$/.test(bi) ? Number(bi) : null;
+    if (an !== null && bn !== null) {
+      if (an !== bn) return an < bn ? -1 : 1;
+    } else if (an !== null) return -1;
+    else if (bn !== null) return 1;
+    else if (ai !== bi) return ai < bi ? -1 : 1;
+  }
+  return 0;
+}
+function satisfiesSystemPin(systemVersion, range) {
+  const op = range.startsWith("^") ? "^" : range.startsWith("~") ? "~" : "";
+  const base = parseSemver(op === "" ? range : range.slice(1));
+  const version = parseSemver(systemVersion);
+  if (base === null || version === null) return false;
+  if (op === "") return compareSemver(version, base) === 0;
+  if (version.prerelease.length > 0) {
+    const sameTuple = version.major === base.major && version.minor === base.minor && version.patch === base.patch;
+    if (!sameTuple || base.prerelease.length === 0) return false;
+  }
+  if (compareSemver(version, base) < 0) return false;
+  if (op === "~") return version.major === base.major && version.minor === base.minor;
+  if (base.major > 0) return version.major === base.major;
+  if (base.minor > 0) return version.major === 0 && version.minor === base.minor;
+  return version.major === 0 && version.minor === 0 && version.patch === base.patch;
+}
+var ABILITY_V1_JSON_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://helixb.dev/schemas/ability-v1.schema.json",
+  title: "HELIX Ability Bundle Manifest v1",
+  description: 'The system-owned payload of a kind:ability platform bundle; lives at the bundle root as ability.json and is the single authoring surface \u2014 the platform envelope (helix.json) is derived from it at publish. Beyond this schema, the reference validator (@helix/humanoid-character/ability-manifest) enforces: action ids and clip names are namespaced "<id>.<name>"; a manual activation action must be declared in actions; additiveRef must name a clip in this manifest; action ids and clip names are unique; the ability id may not be a reserved config prefix (character, abilities).',
+  type: "object",
+  additionalProperties: false,
+  required: ["schemaVersion", "id", "version", "title", "system", "activation", "configSchema", "entry"],
+  properties: {
+    $schema: { type: "string", description: "Editor convenience \u2014 ignored by the validator." },
+    schemaVersion: { const: 1, description: "Payload schema version. Post-freeze changes bump this (ability-v2), never edit v1." },
+    id: {
+      type: "string",
+      pattern: ABILITY_ID_PATTERN,
+      description: "Ability id (platform slug rules: 3-50 chars, lowercase letters/digits/hyphens, no leading/trailing hyphen). Namespaces the config mount (<id>.*), clip names, and action ids. Becomes the platform slug at publish."
+    },
+    version: { type: "string", pattern: SEMVER_PATTERN, description: "Semver version of this ability bundle." },
+    title: { type: "string", minLength: 1, description: "Display name for catalogs and agent discovery." },
+    description: { type: "string", description: "What the ability does \u2014 agent- and human-facing." },
+    system: {
+      type: "object",
+      additionalProperties: false,
+      required: ["id", "version", "skeleton"],
+      description: "The host system this ability targets. Validated by the CLI at install and by the runtime at load; a mismatch refuses the bundle.",
+      properties: {
+        id: { type: "string", pattern: ABILITY_ID_PATTERN, description: "System id, e.g. 'humanoid-character'." },
+        version: {
+          type: "string",
+          pattern: SYSTEM_RANGE_PATTERN,
+          description: "Semver range the running system version must satisfy: exact 'x.y.z', caret '^x.y.z', or tilde '~x.y.z' (npm semantics)."
+        },
+        skeleton: { type: "string", pattern: SKELETON_PATTERN, description: "Skeleton standard tag, exact-matched at load, e.g. 'helix-humanoid@1'." }
+      }
+    },
+    activation: {
+      description: "How the ability becomes active. 'always': activated at world load. 'manual': the manager auto-binds the declared action and toggles/holds activation on it. 'contextual': blackboard conditions (the AnimGraph condition grammar) evaluated per tick \u2014 enter-activate, exit-deactivate. Channel claims bind to activation, not install.",
+      oneOf: [
+        {
+          type: "object",
+          additionalProperties: false,
+          required: ["mode"],
+          properties: { mode: { const: "always" } }
+        },
+        {
+          type: "object",
+          additionalProperties: false,
+          required: ["mode", "action", "style"],
+          properties: {
+            mode: { const: "manual" },
+            action: { type: "string", description: "A qualified action id declared in actions, e.g. 'fly.toggle'." },
+            style: { enum: [...ACTIVATION_STYLES], description: "'toggle' flips activation on press; 'hold' activates while held." }
+          }
+        },
+        {
+          type: "object",
+          additionalProperties: false,
+          required: ["mode", "when"],
+          properties: {
+            mode: { const: "contextual" },
+            when: {
+              type: "array",
+              minItems: 1,
+              description: 'AND-ed [param, op, value] conditions over blackboard parameters, e.g. [["inWater", "==", true]]. Parameters the world must publish are part of the ability contract \u2014 document them in description.',
+              items: {
+                type: "array",
+                minItems: 3,
+                maxItems: 3,
+                prefixItems: [
+                  { type: "string", pattern: CONDITION_PARAM_PATTERN, description: "Blackboard parameter name." },
+                  { enum: [...CONDITION_OPS], description: "Comparison operator." },
+                  { type: ["number", "boolean"], description: "Comparison operand." }
+                ],
+                items: false
+              }
+            }
+          }
+        }
+      ]
+    },
+    channels: {
+      type: "object",
+      description: 'Exclusive channels claimed when the ability activates and released when it deactivates, e.g. { "movement": { "priority": 10 } }. Higher priority displaces (suspends) lower; the displaced holder resumes when the channel frees.',
+      propertyNames: { pattern: CHANNEL_NAME_PATTERN },
+      additionalProperties: {
+        type: "object",
+        additionalProperties: false,
+        required: ["priority"],
+        properties: { priority: { type: "number", minimum: 0, description: "Claim priority; built-in locomotion holds movement at 0." } }
+      }
+    },
+    actions: {
+      type: "array",
+      description: "Input actions registered at install. Ids are namespaced by the ability id.",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["id"],
+        properties: {
+          id: { type: "string", description: "Qualified action id '<abilityId>.<action>', e.g. 'fly.toggle'." },
+          kind: { enum: ["button", "toggle", "vec2"], default: "button", description: "Action kind (mirrors the system input service)." },
+          defaultBinding: {
+            type: "object",
+            additionalProperties: false,
+            description: "Default KB/M + standard-gamepad bindings; omitted = unbound until rebound. Mirrors the system ActionBindings shape.",
+            properties: {
+              keys: { type: "array", items: { type: "string" }, description: "KeyboardEvent.code values." },
+              composite: {
+                type: "object",
+                additionalProperties: false,
+                description: "Keyboard composite for vec2 actions; +y is forward, +x is right.",
+                properties: {
+                  up: { type: "array", items: { type: "string" } },
+                  down: { type: "array", items: { type: "string" } },
+                  left: { type: "array", items: { type: "string" } },
+                  right: { type: "array", items: { type: "string" } }
+                }
+              },
+              mouseButtons: { type: "array", items: { type: "integer", minimum: 0 }, description: "MouseEvent.button values (0 = left, 2 = right)." },
+              gamepadButtons: { type: "array", items: { type: "integer", minimum: 0 }, description: "Standard-mapping gamepad button indices." },
+              gamepadAxes: {
+                type: "array",
+                minItems: 2,
+                maxItems: 2,
+                items: { type: "integer", minimum: 0 },
+                description: "[xAxisIndex, yAxisIndex] into Gamepad.axes."
+              },
+              deadzone: { type: "number", minimum: 0, exclusiveMaximum: 1, description: "Radial stick deadzone, default 0.15." }
+            }
+          }
+        }
+      }
+    },
+    clips: {
+      type: "array",
+      description: "Animation clips fetched and registered at load. Names are namespaced by the ability id; meta fields mirror clip-meta.json.",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["name", "src"],
+        properties: {
+          name: { type: "string", description: "Qualified clip name '<abilityId>.<clip>', e.g. 'fly.hover'." },
+          src: { type: "string", pattern: CLIP_SRC_PATTERN, description: "Bundle-relative .glb/.gltf path (no leading '/', no '..')." },
+          loop: { type: "boolean", default: true },
+          strideSpeed: { type: ["number", "null"], description: "Measured ground speed (m/s) of the source motion; null for non-travelling clips." },
+          additive: { type: "boolean", description: "Tracks are pre-baked deltas \u2014 bound with additive blend." },
+          additiveRef: { type: "string", description: "Qualified name of another clip in this manifest to derive the additive delta against." },
+          direction: { type: "number", description: "Signed travel direction (deg, gait-F = 0) for directional locomotion clips." }
+        }
+      }
+    },
+    configSchema: {
+      type: "string",
+      pattern: SCHEMA_PATH_PATTERN,
+      description: "Bundle-relative path to the JSON Schema for this ability's config, mounted at the ability id (fly.maxSpeed). Mandatory \u2014 the manifest is the documentation agents discover tunables from."
+    },
+    entry: {
+      type: "string",
+      pattern: ENTRY_PATH_PATTERN,
+      description: "Bundle-relative ESM entry; its default export is a class implementing the system Ability interface."
+    }
+  }
+};
+
+// src/core/identity.ts
+var SYSTEM_ID = "humanoid-character";
+var SYSTEM_VERSION = "0.2.2";
+var SKELETON_STANDARD = "helix-humanoid@1";
+var SYSTEM_IDENTITY = { id: SYSTEM_ID, version: SYSTEM_VERSION, skeleton: SKELETON_STANDARD };
+export {
+  ABILITY_ID_PATTERN,
+  ABILITY_V1_JSON_SCHEMA,
+  ACTIVATION_MODES,
+  ACTIVATION_STYLES,
+  AbilityManifestError,
+  CHANNEL_NAME_PATTERN,
+  CLIP_SRC_PATTERN,
+  CONDITION_OPS,
+  CONDITION_PARAM_PATTERN,
+  ENTRY_PATH_PATTERN,
+  LOCAL_NAME_PATTERN,
+  RESERVED_CONFIG_PREFIXES,
+  SCHEMA_PATH_PATTERN,
+  SEMVER_PATTERN,
+  SKELETON_PATTERN,
+  SKELETON_STANDARD,
+  SYSTEM_ID,
+  SYSTEM_IDENTITY,
+  SYSTEM_RANGE_PATTERN,
+  SYSTEM_VERSION,
+  compareSemver,
+  parseAbilityManifest,
+  parseSemver,
+  satisfiesSystemPin,
+  validateAbilityManifest
+};

package/vendor/installed-index.mjs

@@ -0,0 +1,71 @@
+// @helix/humanoid-character@0.2.2 — installed.json (install-index) validator.
+// Consumer/loader contract: VERSIONED and NON-frozen (NOT ability-v1). Generated by emit-schemas; regenerate freely.
+
+// src/bundle/installedIndex.ts
+var ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]{1,48})[a-z0-9]$/;
+var SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;
+var REL_PATH_PATTERN = /^(?!\/)(?!.*\.\.)[A-Za-z0-9._/-]+$/;
+var ABS_URL_PATTERN = /^https?:\/\/\S+$/;
+var ALLOWED_KEYS = /* @__PURE__ */ new Set(["id", "version", "codeUrl", "assetBaseUrl", "path"]);
+function typeName(v) {
+  return v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
+}
+function isResolvedEntry(entry) {
+  return typeof entry.codeUrl === "string";
+}
+function validCodeUrl(v) {
+  return typeof v === "string" && !v.includes("..") && (ABS_URL_PATTERN.test(v) || REL_PATH_PATTERN.test(v));
+}
+function validateInstalledIndex(value) {
+  const issues = [];
+  if (!Array.isArray(value)) {
+    issues.push({ path: "", message: `installed.json must be an array of entries (got ${typeName(value)})` });
+    return issues;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  value.forEach((entry, i) => {
+    const at = (k) => k ? `[${i}].${k}` : `[${i}]`;
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      issues.push({ path: at(""), message: `must be an object (got ${typeName(entry)})` });
+      return;
+    }
+    const e = entry;
+    if (typeof e.id !== "string" || !ID_PATTERN.test(e.id)) {
+      issues.push({ path: at("id"), message: "must be a platform slug (3-50 chars: a-z, 0-9, hyphen; no leading/trailing hyphen)" });
+    } else {
+      if (seen.has(e.id)) issues.push({ path: at("id"), message: `duplicate ability id '${e.id}'` });
+      seen.add(e.id);
+    }
+    if (typeof e.version !== "string" || !SEMVER_PATTERN.test(e.version)) {
+      issues.push({ path: at("version"), message: "must be a semver version like 1.0.0" });
+    }
+    const hasResolved = "codeUrl" in e || "assetBaseUrl" in e;
+    const hasLocal = "path" in e;
+    if (hasResolved && hasLocal) {
+      issues.push({ path: at(""), message: "entry must be EITHER { codeUrl, assetBaseUrl } (resolved) OR { path } (local), not both" });
+    } else if (hasResolved) {
+      if (!validCodeUrl(e.codeUrl)) {
+        issues.push({ path: at("codeUrl"), message: 'must be an absolute http(s) URL (CDN) or an index-relative path like "fly" (no leading "/", no "..")' });
+      }
+      if (typeof e.assetBaseUrl !== "string" || !ABS_URL_PATTERN.test(e.assetBaseUrl)) {
+        issues.push({ path: at("assetBaseUrl"), message: "must be an absolute http(s) URL \u2014 assets always stream from the CDN" });
+      }
+    } else if (hasLocal) {
+      if (typeof e.path !== "string" || !REL_PATH_PATTERN.test(e.path)) {
+        issues.push({ path: at("path"), message: "must be an index-relative path (no leading '/', no '..')" });
+      }
+    } else {
+      issues.push({ path: at(""), message: "entry needs { codeUrl, assetBaseUrl } (resolved) or { path } (local)" });
+    }
+    for (const key of Object.keys(e)) {
+      if (!ALLOWED_KEYS.has(key)) {
+        issues.push({ path: at(key), message: "unknown field (allowed: id, version, codeUrl, assetBaseUrl, path)" });
+      }
+    }
+  });
+  return issues;
+}
+export {
+  isResolvedEntry,
+  validateInstalledIndex
+};